Opened 3 years ago
Closed 3 years ago
#32654 closed Uncategorized (wontfix)
docstring in modules created by startapp
| Reported by: | Sandro Covo | Owned by: | nobody |
|---|---|---|---|
| Component: | Core (Management commands) | Version: | 3.2 |
| Severity: | Normal | Keywords: | startapp documentation |
| Cc: | Triage Stage: | Unreviewed | |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | yes | UI/UX: | no |
Description
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".
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.