From 64ad585cfc749bb6615dcc3427ce99634f2dd882 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 23 Feb 2024 14:31:15 -0500 Subject: [PATCH] Build online docs (RTD) with -W and dependencies This configures Read the Docs builds to be more like local builds in two ways: - Pass "-W", as is done in a local build with "make -C doc html", so that if there are broken references, the build fails. - Install dependencies. This configures the Python environment, via the python.install key, so that RTD builds install requirements. More specifically on dependency installation, it does two things: 1. The equivalent of "pip install .", which installs the project and its dependencies (though not any extras). This includes the gitdb dependency, which is needed to import GitPython's git module to populate sections in the API Reference page (#1840). 2. The equivalent of "pip install -r doc/requirements.txt", which installs the additional Sphinx-related dependencies used when building documentation locally. Installing Sphinx-related dependencies is useful for three reasons: a. Least importantly, it should increase consistency between remote (RTD) and local documentation builds. b. It may be needed to avoid warnings that are not being fixed at this time, while still allowing the build to succeed with the "-W" option (see above on that change) that causes failure for immediately addressable problems. The effect of newer versions of Sphinx carrying a few extra hard-to-fix warnings for GitPython is noted in #1802 (and is why they are not upgraded in #1803). c. One of the documentation build dependencies listed in doc/requirements.txt is sphinx_rtd_theme. In 634151a (for #1794) the line specifying this theme was commented out, since it apparently broke in the build. This may allow it to be used again (or can be replaced with another custom theme if desired). This also reenables the sphinx_rtd_theme theme disabled in 634151a. Finally, this makes minor changes to .readthedocs.yml's comments and formatting so the comments are accurate for GitPython details and so the file is formatted in the same style as other YAML here. --- .readthedocs.yaml | 22 ++++++++++++---------- doc/source/conf.py | 2 +- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3a73b5a3c..04275ce72 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,7 +4,7 @@ # Required version: 2 -# Set the OS, Python version and other tools you might need +# Set the OS, Python version and other tools you might need. build: os: ubuntu-22.04 tools: @@ -14,22 +14,24 @@ build: # rust: "1.70" # golang: "1.20" -# Build documentation in the "docs/" directory with Sphinx +# Build documentation in the "doc/" directory with Sphinx. sphinx: configuration: doc/source/conf.py # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs # builder: "dirhtml" # Fail on all warnings to avoid broken references - # fail_on_warning: true + fail_on_warning: true -# Optionally build your docs in additional formats such as PDF and ePub +# Optionally build your docs in additional formats such as PDF and ePub. # formats: -# - pdf -# - epub +# - pdf +# - epub # Optional but recommended, declare the Python requirements required -# to build your documentation +# to build your documentation. # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +python: + install: + - method: pip + path: . + - requirements: doc/requirements.txt diff --git a/doc/source/conf.py b/doc/source/conf.py index ea7a28291..9c22ca06a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -93,7 +93,7 @@ # Options for HTML output # ----------------------- -# html_theme = "sphinx_rtd_theme" +html_theme = "sphinx_rtd_theme" html_theme_options = {} # The name for this set of Sphinx documents. If None, it defaults to