sphinx-doc/sphinx

Can't extend builtin theme if it doesn't have explicit layout.html

Open

#12,049 opened on Mar 6, 2024

View on GitHub
 (22 comments) (0 reactions) (1 assignee)Python (5,625 stars) (1,985 forks)batch import
help wantedhtml themetype:bug

Description

Describe the bug

A theme that customizes layout.html cannot inherit from a theme that has an inherited layout.html and does not explicitly have its own, e.g., default, nature, sphinxdoc, or traditional.

How to Reproduce

If I add a custom theme to lumache that inherits from a builtin theme:

diff --git a/docs/source/_themes/lumache/layout.html b/docs/source/_themes/lumache/layout.html
new file mode 100644
index 0000000..7170ae5
--- /dev/null
+++ b/docs/source/_themes/lumache/layout.html
@@ -0,0 +1 @@
+{% extends "!layout.html" %}
diff --git a/docs/source/_themes/lumache/theme.conf b/docs/source/_themes/lumache/theme.conf
new file mode 100644
index 0000000..ffeaaf1
--- /dev/null
+++ b/docs/source/_themes/lumache/theme.conf
@@ -0,0 +1,2 @@
+[theme]
+inherit = sphinxdoc
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4ea7454..7e23856 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -24,5 +24,6 @@ exclude_patterns = []
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'lumache'
+html_theme_path = ['_themes']
 html_static_path = ['_static']

I get

Theme error:
An error happened in rendering the page index.
Reason: RecursionError('maximum recursion depth exceeded')
Running Sphinx v7.1.2
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
Theme error:
An error happened in rendering the page index.
Reason: RecursionError('maximum recursion depth exceeded')

If I change my layout.html to explicitly extend on the inherited layout

diff --git a/docs/source/_themes/lumache/layout.html b/docs/source/_themes/lumache/layout.html
index 7170ae5..a61bb33 100644
--- a/docs/source/_themes/lumache/layout.html
+++ b/docs/source/_themes/lumache/layout.html
@@ -1 +1 @@
-{% extends "!layout.html" %}
+{% extends "sphinxdoc/layout.html" %}

I get

Theme error:
An error happened in rendering the page index.
Reason: TemplateNotFound('sphinxdoc/layout.html')
Running Sphinx v7.1.2
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
Theme error:
An error happened in rendering the page index.
Reason: TemplateNotFound('sphinxdoc/layout.html')

It only works if I have layout.html explicitly extend on the redirected layout.html

diff --git a/docs/source/_themes/lumache/layout.html b/docs/source/_themes/lumache/layout.html
index a61bb33..0f710c9 100644
--- a/docs/source/_themes/lumache/layout.html
+++ b/docs/source/_themes/lumache/layout.html
@@ -1 +1 @@
-{% extends "sphinxdoc/layout.html" %}
+{% extends "basic/layout.html" %}

Environment Information

Platform:              darwin; (macOS-14.3.1-arm64-arm-64bit)
Python version:        3.12.2 | packaged by conda-forge | (main, Feb 16 2024, 20:54:21) [Clang 16.0.6 ])
Python implementation: CPython
Sphinx version:        7.1.2
Docutils version:      0.20.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

[]

Additional context

Possibly related to #1792, #1794, #1884, #1885

Contributor guide