[Django] #32654: docstring in modules created by startapp
Django
-------------------------------------+-------------------------------------
Reporter: Sandro | Owner: nobody
Covo |
Type: | Status: new
Uncategorized |
Component: Core | Version: 3.2
(Management commands) | Keywords: startapp
Severity: Normal | documentation
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-------------------------------------+-------------------------------------
I propose to add a docstring to the files created by startapp, similar to
the docstrings that are included in the modules created by `startproject`.
They could include some information about when and for what version they
were generated and some directions for users on what to do in the modules.
The `models.py` for example includes a comment `# create your models here`
or `# Create your views here.`, which I think is not extremely helpful,
either you know about models already, in which case you would know what to
do without this comment. Or you don't know anything about models, in which
case you need more information on how to proceed. I suggest having a short
paragraph about the modules with a link to the django documentation. I
think that serves new users as well as more experienced users, if the want
to look something up.
For some modules it might make sense to include a bit of a template for an
actual docstring, maybe like: "This module contains the models for the
{{appname}}-app".
--
Ticket URL: <https://code.djangoproject.com/ticket/32654>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: Uncategorized | Status: closed
Component: Core (Management | Version: 3.2
commands) |
Severity: Normal | Resolution: wontfix
Keywords: startapp | Triage Stage:
documentation | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => closed
* resolution: => wontfix
Comment:
I'm going to say wontfix here: the templates used to be more complicated,
but were deliberately simplified as the included details were not really
read, were not as detailed as the docs, and were considered overwhelming.
The consensus was to keep the templates clean and have users go to the
docs, which will always be canonical and provide either tutorial, guide,
or reference detail at the level which is appropriate for the user in
hand.
See discussion: https://groups.google.com/g/django-
developers/c/y2VJgVXJuMo/m/tBtioYUvphcJ
A change of policy would require agreement on the DevelopersMailingList,
but given the past discussion I would suspect that to be unlikely.
--
Ticket URL: <https://code.djangoproject.com/ticket/32654#comment:1>