From 5b6f8c60cf26ed0d4d419ca28b764fb7f7616a74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Kundr=C3=A1t?= Date: Wed, 13 Mar 2024 18:42:23 +0100 Subject: [PATCH] docs: use the default theme on ReadTheDocs.org as well Historically, we've been using the RTD theme on the RTD site which hosts the docs for us, and a Sphinx-default, "Alabaster" theme for other docs builds. Doing that however started failing: Traceback (most recent call last): File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1096, in handle_page output = self.templates.render(templatename, ctx) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/readthedocs_ext/readthedocs.py", line 181, in rtd_render content = old_render(template, render_context) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 194, in render return self.environment.get_template(template).render(context) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/environment.py", line 1301, in render self.environment.handle_exception() File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/environment.py", line 936, in handle_exception raise rewrite_traceback_stack(source=source) File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code {%- extends "layout.html" %} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/classic/layout.html", line 10, in top-level template code {%- extends "basic/layout.html" %} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 170, in top-level template code {%- block content %} File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 189, in block 'content' {%- block sidebar2 %}{{ sidebar() }}{% endblock %} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 189, in block 'sidebar2' {%- block sidebar2 %}{{ sidebar() }}{% endblock %} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/sandbox.py", line 393, in call return __context.call(__obj, *args, **kwargs) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/jinja2/runtime.py", line 777, in _invoke rv = self._func(*arguments) ^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/themes/default/../basic/layout.html", line 63, in template {%- include sidebartemplate %} ^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/jinja2glue.py", line 215, in get_source raise TemplateNotFound(template) jinja2.exceptions.TemplateNotFound: about.html The above exception was the direct cause of the following exception: Traceback (most recent call last): File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/cmd/build.py", line 281, in build_main app.build(args.force_all, args.filenames) File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/application.py", line 347, in build self.builder.build_update() File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 310, in build_update self.build(to_build, File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 376, in build self.write(docnames, list(updated_docnames), method) File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 571, in write self._write_serial(sorted(docnames)) File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 581, in _write_serial self.write_doc(docname, doctree) File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 672, in write_doc self.handle_page(docname, ctx, event_arg=doctree) File "/home/docs/checkouts/readthedocs.org/user_builds/gnpy/envs/499/lib/python3.12/site-packages/sphinx/builders/html/__init__.py", line 1103, in handle_page raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") % sphinx.errors.ThemeError: An error happened in rendering the page about-project. Reason: TemplateNotFound('about.html') Theme error: An error happened in rendering the page about-project. Reason: TemplateNotFound('about.html') I have no clue what that means because we have never requested this `about.html`, nor do we reference that file from anywhere. Chances are that it's "just" some version pinning/compatibility issue, but hey -- why mess with that when there's a perfectly good default theme that we're using for other purposes already. As a side effect, this also solves that long-standing issue that Esther reported where the tables have overly long lines. Apparently, it's a theme-specific misfeature (readthedocs/sphinx_rtd_theme/#117), and the Alabaster one doesn't suffer from that. All hail alabaster! Change-Id: I857890f29f14b7c0f66bca201c9a9c1b1cbf8841 --- docs/conf.py | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5416461cc..b20001c66 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -84,18 +84,11 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -on_rtd = os.environ.get('READTHEDOCS') == 'True' -if on_rtd: - html_theme = 'default' - html_theme_options = { - 'logo_only': True, - } -else: - html_theme = 'alabaster' - html_theme_options = { - 'logo': 'images/GNPy-logo.png', - 'logo_name': False, - } +html_theme = 'alabaster' +html_theme_options = { + 'logo': 'images/GNPy-logo.png', + 'logo_name': False, +} html_logo = 'images/GNPy-logo.png'