From f02303cd9a5c9d6adf0c44c1efcc10fde4033250 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Tue, 8 Oct 2024 17:20:27 +0200 Subject: [PATCH] RTD: Fix `sphinx-build-compatibility` for use on CrateDB projects When invoking Sphinx standalone, we need to preconfigure a few variables to make the RTD compatibility package work. --- src/crate/theme/rtd/conf/__init__.py | 33 +++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/src/crate/theme/rtd/conf/__init__.py b/src/crate/theme/rtd/conf/__init__.py index 0e3418f0..478247f1 100644 --- a/src/crate/theme/rtd/conf/__init__.py +++ b/src/crate/theme/rtd/conf/__init__.py @@ -18,6 +18,7 @@ # However, if you have executed another commercial license agreement # with Crate these terms will supersede the license and you may use the # software solely pursuant to the terms of the relevant commercial agreement. +import os from crate.theme import rtd as theme from crate.theme.rtd import __version__ @@ -33,7 +34,6 @@ extensions = [ "myst_parser", - "sphinx_build_compatibility.extension", "sphinx_copybutton", "sphinx_design", "sphinx_design_elements", @@ -194,6 +194,34 @@ def setup(app): + def setup_sphinx_compatibility(): + """ + Resolve problem with `sphinx_build_compatibility` extension. + + Add Sphinx extension at runtime, in order to be able to configure it previously. + This is needed because it has some quirks that reveal themselves when invoked in + non-RTD environments. + + - https://github.com/crate/crate-docs-theme/issues/536 + - https://about.readthedocs.com/blog/2024/07/addons-by-default/ + - https://github.com/readthedocs/sphinx-build-compatibility + """ + + # Extension error (sphinx_build_compatibility.extension): + # Handler for event 'config-inited' threw an exception + # (exception: argument of type 'NoneType' is not iterable) + os.environ.setdefault("READTHEDOCS_GIT_CLONE_URL", "") + + # IndexError: list index out of range + # project_id = response_project["results"][0]["id"] + # Currently needs a valid project on PyPI. Long-term fix should go into upstream code. + os.environ.setdefault("READTHEDOCS_PROJECT", "crate-docs-theme") + + # Exception: 'NoneType' object is not subscriptable + os.environ.setdefault("READTHEDOCS_GIT_COMMIT_HASH", "") + + app.setup_extension("sphinx_build_compatibility.extension") + # Configure Sphinx/RTD to host projects on a custom domain, but also on a non-root resource. def configure_self_hosted_on_path(app_inited): """ @@ -287,6 +315,9 @@ def apply_html_context_custom(app_inited): except Exception as ex: print(f"ERROR: Unable to adjust `html_context`. Reason: {ex}") + # Read The Docs compatibility issues. + setup_sphinx_compatibility() + # Modern / NG / Furo. app.require_sphinx("3.0") app.connect("html-page-context", _html_page_context)