Opened 53 minutes ago
#37150 assigned Cleanup/optimization
Version added/changed text, console tabs missing from RTD preview builds, dirhtml builds, etc.
| Reported by: | Mike Edmunds | Owned by: | Mike Edmunds |
|---|---|---|---|
| Component: | Documentation | Version: | 6.0 |
| Severity: | Normal | Keywords: | sphinx |
| Cc: | James Beard | Triage Stage: | Unreviewed |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
There are several related issues in the docs._ext.djangodocs Sphinx extension. The symptom is missing content in most html-like Sphinx builds, including ReadTheDocs PR preview builds:
- Missing text for
versionaddedandversionchangeddirectives: the html contains an empty<div>where something like "New in Django 6.1" or "Changed in Django development version" should be. - Missing console tabs: the html does not include Windows console examples when they are available.
This affects the html builder (which RTD uses by default), the dirhtml builder, plus htmlhelp and singlehtml.
The fix is for the djangodocs extension to:
- Register
DjangoHTMLTranslatorfor all html-like builders (solves missing version text) - Handle all HTML-like builders in
visit_console_html()andConsoleDirective.run()(solves missing console tabs)
[Currently, the extension only handles version and console directives for a custom "djangohtml" builder—used in the docs/Makefile "html" target—and the "json" builder which is used for the docs.djangoproject.com site.]
Also, the custom DjangoStandaloneHTMLBuilder class can and should be removed. Its only function is generating templatebuiltins.js, which is meant to enable client-side hyperlinking of template tags and filters in code examples. But that feature isn't enabled on docs.djangoproject.com and has been broken in local docs builds since Sphinx 6.0 removed jQuery in 2023. It's effectively dead code.