Fix inconsistency with imports in documentation

[niclas.ahden]

We've noticed that imports are not always included in code snippets which means that snippets are not always safe to copy and paste. It's fine to not have them copy-paste safe, but it should be consistent.

For example
The tutorial includes imports in all of the snippets (eg. "from django.contrib import admin"). Except for at the very bottom where the imports are skipped.
​https://docs.djangoproject.com/en/1.6/intro/tutorial02/

This section has two snippets: one with imports and one without.
​https://docs.djangoproject.com/en/dev/topics/forms/modelforms/#selecting-the-fields-to-use

The imports for this snippet are quite far away in a previous section.
​https://docs.djangoproject.com/en/dev/topics/forms/modelforms/#considerations-regarding-model-s-error-messages

TL;DR should all code snippets be safe to copy and paste?

[Tim Graham]

I don't mind the current state of things. There was a couple of patches a while back that added a lot of imports, e.g. 1fe587d80bfcf062a94252fb532c8ac035c833b9 08b501e7d314e9c45dd51d3ba27b2ecb0287df3b 1d543949d7acc93a172e8a2c9272d8b983a421ef.

The first time a concept is introduced in a section, it probably makes sense to include all imports, but if the example is tweaked later, I don't think the imports need to be repeated.

If there are spots that bother you right now, feel free to send a PR. Otherwise, I don't think we need to keep a ticket open for this.

We'll never be able to make all code snippets safe to copy and paste because examples have example dependencies like from myapp.models import Article.

[niclas.ahden]

The first time a concept is introduced in a section, it probably makes sense to include all imports, but if the example is tweaked later, I don't think the imports need to be repeated.
Agreed

If there are spots that bother you right now, feel free to send a PR. Otherwise, I don't think we need to keep a ticket open for this.
Will do

We'll never be able to make all code snippets safe to copy and paste because examples have example dependencies like from myapp.models import Article.
Couldn't we use dot-imports for those in almost all cases?

Before your comment we had a short discussion with bmispelon about this and agreed that adding a brief guideline to the contributor documentation would be good. The general rule being that snippets should preferably be safe to copy and paste. What do you think?

[Tim Graham]

Sure, we could use dot imports. I guess it would be good to encourage that.

I don't think it's true that snippets should be safe to copy and paste. We use ... in a lot of places where, for example purposes, the contents of a function don't matter. Adding the rest of the method body or whatever the ellipses are replacing is just going to obfuscate the purpose of the example. For example:

from django.forms.models import BaseInlineFormSet

class CustomInlineFormSet(BaseInlineFormSet):
    def clean(self):
        super(CustomInlineFormSet, self).clean()
        # example custom validation across forms in the formset
        for form in self.forms:
            # your custom formset validation
            ...

[Niclas Åhdén <niclas@…>]

In 64ee097b3b33716b10837644f9e18b87f25d606e:

Fixed #22639 -- Added missing imports in docs

Added ModelForm and NON_FIELD_ERRORS imports.

[Tim Graham <timograham@…>]

In aa9a146a69655849d588da7eba4a71a2ea4b6361:

[1.7.x] Fixed #22639 -- Added missing imports in docs

Added ModelForm and NON_FIELD_ERRORS imports.

Backport of 64ee097b3b from master

[niclas.ahden]

After a brief discussion on IRC we agreed that a rough guideline is:

• Include all imports the first time that a concept is introduced in a section. If the example is tweaked within the section the imports should not be repeated.

An example where that wasn't true:

​https://docs.djangoproject.com/en/dev/topics/forms/modelforms/#considerations-regarding-model-s-error-messages

Which benefitted from importing ModelForm since it's included in the section above and below.

PR: ​https://github.com/django/django/pull/2696 (also includes the missing NON_FIELD_ERRORS import in the same snippet)

Similar occurrences will be handled in their own tickets.

Thank you Tim!