Opened 7 months ago
Last modified 3 weeks ago
#35485 assigned New feature
Template documentation for startproject / startapp is very sparse.
Reported by: | Chris Rose | Owned by: | Daniel Rios |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | documentation startapp templates |
Cc: | Chris Rose, Clifford Gama, Carlton Gibson | Triage Stage: | Accepted |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | yes |
Easy pickings: | no | UI/UX: | no |
Description
https://docs.djangoproject.com/en/dev/ref/django-admin/#startproject and https://docs.djangoproject.com/en/dev/ref/django-admin/#cmdoption-startapp-template are what I can find for documentation on how to create a startapp/startproject template, but both of those are very sparse.
Things I can't answer after reading those:
- how do I template file names? Can I, even?
- what, if anything, is required in a template zip?
- can I add other documentation or defaults to an app or project template?
- what is an app file template? What needs to be in there?
- can I ship a template as part of an app wheel?
- can I use a subdirectory of a git repository on github or another forge as a template, or does it have to be the top level directory of those?
Change History (10)
comment:1 by , 7 months ago
Triage Stage: | Unreviewed → Accepted |
---|---|
Type: | Uncategorized → New feature |
comment:2 by , 4 months ago
Cc: | added |
---|
comment:3 by , 8 weeks ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:4 by , 8 weeks ago
Cc: | added |
---|
follow-up: 6 comment:5 by , 7 weeks ago
That’d be great! I’ll contribute my one tip: use {% verbatim %}
in templates that should be left un-touched. Here’s my template: wagtail-tutorial-template. There’s nothing particularly fancy about it, I’m just happy to have figured out how to set it up :')
comment:6 by , 7 weeks ago
Replying to Thibaud Colas:
That’d be great! I’ll contribute my one tip: use
{% verbatim %}
in templates that should be left un-touched. Here’s my template: wagtail-tutorial-template. There’s nothing particularly fancy about it, I’m just happy to have figured out how to set it up :')
Nice find. I'll be sure to include it in the section on how to exclude templates.
comment:7 by , 6 weeks ago
A first draft can be found here: https://github.com/MisterRios/django/blob/ticket_35485/docs/howto/override-project-templates.txt
comment:8 by , 6 weeks ago
Has patch: | set |
---|
comment:9 by , 6 weeks ago
Hello reviewers, I have created a draft of this how to guide.
One thing not working is the two links to the folder of the default templates. Wrapping the link in parentheses does nothing, but it works on a different document. I'm probably missing something.
I know this documentation is not perfect, and I do expect to keep improving it.
Thanks.
comment:10 by , 3 weeks ago
Patch needs improvement: | set |
---|
I will link this as it has a few startproject templates: https://github.com/adamchainz/django-startproject-templates/
It also demonstrates that they can be quite different.
This sounds like you want a how to guide which we can link to in ref docs.