#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 , 10 years ago
comment:2 by , 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?
comment:3 by , 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 , 10 years ago
Triage Stage: | Unreviewed → Accepted |
---|
comment:5 by , 10 years ago
Resolution: | → fixed |
---|---|
Status: | new → closed |
comment:7 by , 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:
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!
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
.