Opened 3 weeks ago

Last modified 2 weeks 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: Yeisrael Dawit Triage Stage: Accepted
Has patch: yes 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 (6)

comment:1 by David Smith, 3 weeks ago

Triage Stage: Unreviewed → Accepted

Thanks Rickey, this seems reasonable to me and Tim was supportive on the forum too.

comment:2 by Yeisrael Dawit, 3 weeks ago

Cc: Yeisrael Dawit added
Owner: changed from Rickey Shideler to Yeisrael Dawit

I am claiming this ticket to update the admin documentation links using the :sourcefile: role as outlined in the description.

in reply to:  2 comment:3 by Rickey Shideler, 3 weeks ago

Replying to Yeisrael Dawit:

I am claiming this ticket to update the admin documentation links using the :sourcefile: role as outlined in the description.

Thanks for your interest! I’d assigned it to myself when opening the ticket because I intended to work on the implementation, and I’ve already started on the changes. Would you mind leaving it assigned to me?

comment:4 by Yeisrael Dawit, 3 weeks ago

Owner: changed from Yeisrael Dawit to Rickey Shideler

comment:5 by Yeisrael Dawit, 3 weeks ago

sure ya, no problem Rickey

comment:6 by Rickey Shideler, 2 weeks ago

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