Linux Documentation
 help / color / mirror / Atom feed
* [PATCH] docs: conf.py: register sphinx_rtd_theme as an extension
@ 2026-11-19 19:51 Sean Lyon
  0 siblings, 0 replies; only message in thread
From: Sean Lyon @ 2026-11-19 19:51 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Shuah Khan, Randy Dunlap, linux-doc, linux-kernel, Sean Lyon

The sphinx_rtd_theme sidebar has collapsible sections. The theme uses
jQuery to add the toctree-expand buttons that control them.

Sphinx 6 stopped bundling jQuery. Since sphinx_rtd_theme 1.2.0, the
theme's setup() enables the sphinxcontrib-jquery extension to load it,
but setup() does not run when the theme is loaded through
html_theme_path. Without jQuery, the buttons are never added, so sidebar
sections cannot be collapsed.

Register sphinx_rtd_theme as an extension so its setup() runs. The
setup() also registers the theme, so html_theme_path is no longer
needed, and sphinx_rtd_theme 3.0 warns that it is deprecated.

Signed-off-by: Sean Lyon <sean@seanlyon.dev>
---
Note for testers: with Sphinx >= 8.1, some pages (e.g. core-api/) expand
more than one sidebar section. This also happens without this patch. It
comes from documents included in multiple toctrees. Sphinx warns about
these documents, but the warnings are only shown with make V=1 htmldocs.
I'm looking into this separately and plan to send an RFC.

Tested with sphinx_rtd_theme 3.1.0 and sphinx_rtd_dark_mode 1.3.0 on
Sphinx 9.2.0, and on min_requirements.txt with sphinx_rtd_theme 1.3.0.
No new build warnings, and the get_html_theme_path deprecation warning
is gone.

 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 5ab26ce89daf..ed15bb80ef87 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -385,7 +385,7 @@ if html_theme in ["sphinx_rtd_theme", "sphinx_rtd_dark_mode"]:
     try:
         import sphinx_rtd_theme
 
-        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+        extensions.append("sphinx_rtd_theme")
 
         # Add any paths that contain custom static files (such as style sheets) here,
         # relative to this directory. They are copied after the builtin static files,

base-commit: 2138148bf44fd84d3e0a863f0e8cb3627cdcc606
-- 
2.56.1


^ permalink raw reply related	[flat|nested] only message in thread

only message in thread, other threads:[~2026-11-19 19:52 UTC | newest]

Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-19 19:51 [PATCH] docs: conf.py: register sphinx_rtd_theme as an extension Sean Lyon

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox