[Django] #22639: Fix inconsistency with imports in documentation
Django
--------------------------------------+--------------------
Reporter: niclas.ahden | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+--------------------
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?
--
Ticket URL: <https://code.djangoproject.com/ticket/22639>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: niclas.ahden | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
Comment:
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`.
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:1>
Django
Reporter: niclas.ahden | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by niclas.ahden):
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?
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:2>
Django
Reporter: niclas.ahden | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: master
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
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
...
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:3>
Django
Reporter: niclas.ahden | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:4>
Django
Reporter: niclas.ahden | Owner: nobody
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Niclas Åhdén <niclas@…>):
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"64ee097b3b33716b10837644f9e18b87f25d606e"]:
{{{
#!CommitTicketReference repository=""
revision="64ee097b3b33716b10837644f9e18b87f25d606e"
Fixed #22639 -- Added missing imports in docs
Added ModelForm and NON_FIELD_ERRORS imports.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:5>
Django
Reporter: niclas.ahden | Owner: nobody
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"aa9a146a69655849d588da7eba4a71a2ea4b6361"]:
{{{
#!CommitTicketReference repository=""
revision="aa9a146a69655849d588da7eba4a71a2ea4b6361"
[1.7.x] Fixed #22639 -- Added missing imports in docs
Added ModelForm and NON_FIELD_ERRORS imports.
Backport of 64ee097b3b from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:6>
Django
Reporter: niclas.ahden | Owner: nobody
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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!
--
Ticket URL: <https://code.djangoproject.com/ticket/22639#comment:7>