Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#22639 closed Cleanup/optimization (fixed)

Fix inconsistency with imports in documentation

Reported by: niclas.ahden Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Tim Graham, Daniele Procida, tibidat Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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?

Change History (7)

comment:1 by Tim Graham, 10 years ago

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.

comment:2 by niclas.ahden, 10 years ago

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?

Last edited 10 years ago by niclas.ahden (previous) (diff)

comment:3 by Tim Graham, 10 years ago

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
            ...

comment:4 by Tim Graham, 10 years ago

Triage Stage: UnreviewedAccepted

comment:5 by Niclas Åhdén <niclas@…>, 10 years ago

Resolution: fixed
Status: newclosed

In 64ee097b3b33716b10837644f9e18b87f25d606e:

Fixed #22639 -- Added missing imports in docs

Added ModelForm and NON_FIELD_ERRORS imports.

comment:6 by Tim Graham <timograham@…>, 10 years ago

In aa9a146a69655849d588da7eba4a71a2ea4b6361:

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

Added ModelForm and NON_FIELD_ERRORS imports.

Backport of 64ee097b3b from master

comment:7 by niclas.ahden, 10 years ago

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!

Note: See TracTickets for help on using tickets.
Back to Top