[Django] #35485: Template documentation for startproject / startapp is very sparse.

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: offbyone | Owner: nobody
Type: | Status: new
Uncategorized |
Component: | Version: dev
Documentation | Keywords: documentation
Severity: Normal | startapp templates
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
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?
--
Ticket URL: <https://code.djangoproject.com/ticket/35485>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------

Reporter: Chris Rose | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted
* type: Uncategorized => New feature

Comment:

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 [https://docs.djangoproject.com/en/5.0/howto/
how to guide] which we can link to in ref docs.
--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:1>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Clifford Gama):

* cc: Clifford Gama (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:2>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------

Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Daniel Rios):

* owner: nobody => Daniel Rios
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:3>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Carlton Gibson):

* cc: Carlton Gibson (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:4>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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:
[https://github.com/thibaudcolas/wagtail-tutorial-template wagtail-
tutorial-template]. There’s nothing particularly fancy about it, I’m just
happy to have figured out how to set it up :')
--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:5>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Daniel Rios):

Replying to [comment:5 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:
[https://github.com/thibaudcolas/wagtail-tutorial-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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:6>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Daniel Rios):

A first draft can be found here:
https://github.com/MisterRios/django/blob/ticket_35485/docs/howto
/override-project-templates.txt
--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:7>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Daniel Rios):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:8>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Daniel Rios):

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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:9>

[Django]

#35485: Template documentation for startproject / startapp is very sparse.
-------------------------------------+-------------------------------------
Reporter: Chris Rose | Owner: Daniel
| Rios
Type: New feature | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation | Triage Stage: Accepted
startapp templates |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35485#comment:10>