I recently worked on ticket #37127 which ended up adding a version aware:sourcefile: Sphinx role and used it to link to Django’s builtin form templates.
Now that it exists, I’m wondering if there are other instances that should be linked as well, and if there should be a specific convention for when docs should link directly to the source files.
Following the idea of the original ticket, my initial thought is that :sourcefile: would be most helpful when a user needs to inspect or customize a file shipped with Django. It seems less necessary when the source file is just an implementation detail.
A few areas that stood out:
- Tutorial 7 The admin template directory is linked, but users are told to copy the admin/base_site.html and admin/index.html files.
- Admin customization The admin template directory is linked, but change_list.html and change_form.html are called out specifically. There is also a list of all of the templates that can be overridden by app or model - I’m not sure that we would necessarily need to link all of those since the admin template directory is already linked.
- Admin list filters (/ref/contrib/admin/filters/) admin/filter.html is called out as a concrete example but is not linked
- Admin theming (/ref/contrib/admin/#theming-support) base.css and dark_mode.css are hard-coded links to github that could be switched to the version-aware links
Also, I noticed that the areas that link to the admin template directories are hard-coded links to github so they are not version aware. Should directory links remain as they are, or would a version-aware source directory role be useful too?
I’m curious whether this seems like a reasonable rule of thumb for :sourcefile:, and whether there are other areas of the docs where it would be useful.
For reference, this came from Trac ticket #37127 and PR #21381.
I was limited to 2 links, otherwise would have linked to each of the files. I also used AI (Codex) to help identify other potential areas that would benefit from the new role.