[Django] #37150: Version added/changed text, console tabs missing from RTD preview builds, dirhtml builds, etc.

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike | Owner: Mike Edmunds
Edmunds |
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: 6.0
Documentation |
Severity: Normal | Keywords: sphinx
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
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 `versionadded` and `versionchanged` directives: 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 `DjangoHTMLTranslator` for all html-like builders (solves
missing version text)
- Handle all HTML-like builders in `visit_console_html()` and
`ConsoleDirective.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.
--
Ticket URL: <https://code.djangoproject.com/ticket/37150>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------

Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: sphinx | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Mike Edmunds):

* has_patch: 0 => 1

Comment:

https://github.com/django/django/pull/21440.

[The djangodocs Sphinx extension and theme template files are
undocumented, so I think deprecation would not apply to the removed code.]
--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:1>

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: sphinx | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted

Comment:

Thank you Mike, this makes sense. Will review the PR soon!
--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:2>

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: sphinx | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:3>

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds

Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed

Keywords: sphinx | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by nessita <124304+nessita@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"9b1db9cb2c38c75b8fb0fc64ba5f73a6012e5b2d" 9b1db9c]:
{{{#!CommitTicketReference repository=""
revision="9b1db9cb2c38c75b8fb0fc64ba5f73a6012e5b2d"
Fixed #37150 -- Made djangodocs Sphinx extension work with any html
builder.

Changed djangodocs extension to register DjangoHTMLTranslator for any
html-format builder (in the builder-inited hook), rather than a limited
list of builders at startup. That fixes missing content in dirhtml and
standard html builds (including ReadTheDocs PR previews):
- Missing console tabs
- Empty divs for versionadded and versionchanged directives

Removed JS code that depended on jQuery, which hasn't worked since
Sphinx 6.0 dropped jQuery in 2023:
- Unnecessary console tabs click handling. (Console tab behavior is
implemented purely in CSS.)
- Client-side hyperlinking of Django template tags and filters in code
examples. (This is also not supported on docs.djangoproject.com.)

Removed custom DjangoStandaloneHTMLBuilder and "djangohtml" builder
type. Its sole purpose was to generate the "templatebuiltins.js" file
used for the (non-functional) client-side template filter/tag linking.

Changed docs "make html" target from "djangohtml" to standard "html".
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:4>

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed
Keywords: sphinx | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"a09323d832585a867a509f0decc670c699ca9c3a" a09323d]:
{{{#!CommitTicketReference repository=""
revision="a09323d832585a867a509f0decc670c699ca9c3a"
[6.1.x] Fixed #37150 -- Made djangodocs Sphinx extension work with any

html builder.

Changed djangodocs extension to register DjangoHTMLTranslator for any
html-format builder (in the builder-inited hook), rather than a limited
list of builders at startup. That fixes missing content in dirhtml and
standard html builds (including ReadTheDocs PR previews):
- Missing console tabs
- Empty divs for versionadded and versionchanged directives

Removed JS code that depended on jQuery, which hasn't worked since
Sphinx 6.0 dropped jQuery in 2023:
- Unnecessary console tabs click handling. (Console tab behavior is
implemented purely in CSS.)
- Client-side hyperlinking of Django template tags and filters in code
examples. (This is also not supported on docs.djangoproject.com.)

Removed custom DjangoStandaloneHTMLBuilder and "djangohtml" builder
type. Its sole purpose was to generate the "templatebuiltins.js" file
used for the (non-functional) client-side template filter/tag linking.

Changed docs "make html" target from "djangohtml" to standard "html".

Backport of 9b1db9cb2c38c75b8fb0fc64ba5f73a6012e5b2d from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:5>

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed
Keywords: sphinx | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by GitHub <noreply@…>):

In [changeset:"bc65586cfb69c0c0c399e40a22494501e0da2008" bc65586c]:
{{{#!CommitTicketReference repository=""
revision="bc65586cfb69c0c0c399e40a22494501e0da2008"
Refs #37150 -- Synced docs/make.bat with docs/Makefile.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:6>

[Django]

#37150: Version added/changed text, console tabs missing from RTD preview builds,
dirhtml builds, etc.
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: closed
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: fixed
Keywords: sphinx | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"3a5c377203b658cf3676d87a756e57b56fd1b2a5" 3a5c377]:
{{{#!CommitTicketReference repository=""
revision="3a5c377203b658cf3676d87a756e57b56fd1b2a5"
[6.1.x] Refs #37150 -- Synced docs/make.bat with docs/Makefile.

Backport of bc65586cfb69c0c0c399e40a22494501e0da2008 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37150#comment:7>