Opened 58 minutes ago

#37458 assigned Cleanup/optimization

Add source links for customizable templates and assets in admin documentation

Reported by: Rickey Shideler Owned by: Rickey Shideler
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

Several sections of Django's admin documentation reference specific templates and static files that developers may need to customize or inspect. Although some sections link to the overall admin template directory, individual files are not always linked, requiring developers to manually find them.

Ticket - #37127 introduced a version-aware :sourcefile: Sphinx role, which could be used to make these files easier to access directly from the docs.

A few areas that could benefit from this:

  • ​Tutorial 7 — Link admin/base_site.html and admin/index.html, which developers are instructed to copy and customize.
  • ​Admin template customization — Link specific templates such as change_form.html and change_list.html where developers are encouraged to inspect or override them.
  • ​Admin list filters — Link admin/filter.html, which is referenced as a concrete example for creating custom filter templates.
  • ​Admin theming — Replace the existing hard-coded GitHub links to base.css and dark_mode.css with :sourcefile: links so they point to the corresponding Django source version.

The goal would be to link individual Django-provided files where the documentation specifically encourages developers to inspect or customize them, rather than linking every file mentioned in the documentation.

Related tickets:

  • #37127 — Added version-aware source links for form templates.
  • #33842 — Added links to source paths in the documentation.

Forum discussion: ​https://forum.djangoproject.com/t/when-should-docs-link-to-source-files/45949

Change History (0)

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