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 Sarah Boyce, 7 months ago

Triage Stage: UnreviewedAccepted
Type: UncategorizedNew feature

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.

comment:2 by Clifford Gama, 4 months ago

Cc: Clifford Gama added

comment:3 by Daniel Rios, 8 weeks ago

Owner: changed from nobody to Daniel Rios
Status: newassigned

comment:4 by Carlton Gibson, 8 weeks ago

Cc: Carlton Gibson added

comment:5 by Thibaud Colas, 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 :')

in reply to:  5 comment:6 by Daniel Rios, 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:8 by Daniel Rios, 6 weeks ago

Has patch: set

comment:9 by Daniel Rios, 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 Sarah Boyce, 3 weeks ago

Patch needs improvement: set
Note: See TracTickets for help on using tickets.
Back to Top