Opened 5 years ago

Closed 2 months ago

#25712 closed Cleanup/optimization (fixed)

Template overview documentation is not very approachable

Reported by: Jacek Bzdak Owned by: David Smith
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


Template overview documentation is not very approachable for new people as it starts with multiple pages of text, that is really about new plug-in templates. I'm doing a course on Django (in Warsaw University Of Technology), and I was browsing for some document that I can point students to and say: "If you have more time before classes read that".

Pluggable template engines (and template engine configuration) are pretty advanced subjects so ideally they should be on their own page.

I'd suggest the flowing:

  • "Overview" that assumes default Django configuration, and mentions CONTEXT_PROCESSORS. Also has some very brief introduction to with something along the lines: "Engine templates are now pluggable configuration is there" (and link to other page)
  • Add page about template engine configuration and so on.
  • Move information about create your own backend to it's own page (as it is a very advanced subject --- that in dev tree covers also how to create debug pages for not-built in engines).

Change History (7)

comment:1 Changed 5 years ago by Tim Graham

Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

I think I had similar concerns when reviewing Aymeric's template work, but he convinced me the current organization wasn't completely silly.

Did you find both of these pages?

If you could propose a patch, that would be great. Otherwise, this type of "big reorganization" ticket often languish.

comment:2 Changed 5 years ago by Jacek Bzdak

Owner: changed from nobody to Jacek Bzdak
Status: newassigned

I'll try to do this, in near future.

comment:3 Changed 5 years ago by Aymeric Augustin

More honestly — s/completely silly/sufficiently silly to force him to reorganize it/. I'm not very good at organizing documentation. This would be a welcome contribution.

comment:4 Changed 2 months ago by felixxm

Has patch: set
Owner: changed from Jacek Bzdak to David Smith
Patch needs improvement: set
Version: 1.8master

comment:5 Changed 2 months ago by David Smith

Patch needs improvement: unset

comment:6 Changed 2 months ago by felixxm

Triage Stage: AcceptedReady for checkin

comment:7 Changed 2 months ago by Mariusz Felisiak <felisiak.mariusz@…>

Resolution: fixed
Status: assignedclosed

In bb137114:

Fixed #25712 -- Reorganized templates docs.

Note: See TracTickets for help on using tickets.
Back to Top