docs: upgrade Sphinx and validate documentation builds

.github/workflows/main.yml

@@ -418,14 +418,23 @@ jobs:
             ${{ runner.os }}-uv-
 
       - name: Install Python Dependencies
-        run: uv sync --group ci --no-dev
+        run: uv sync --locked --group ci --no-dev
 
       - name: Add .venv to PATH
         run: echo "${GITHUB_WORKSPACE}/.venv/bin" >> "$GITHUB_PATH"
 
       - name: Build Docs
         run: tox -e docs
 
+      - name: Install PDF build dependencies
+        run: |
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
+            latexmk texlive-latex-recommended texlive-latex-extra \
+            texlive-fonts-recommended tex-gyre xindy
+
+      - name: Build PDF and EPUB
+        run: tox -e docs-formats
+
       - name: Trigger ReadTheDocs build
         if: ${{ github.ref_name == 'trunk' }}
         env:

.readthedocs.yml

@@ -15,7 +15,7 @@ build:
     create_environment:
       - python -m uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
     install:
-      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" python -m uv sync --frozen --group docs --no-dev
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" python -m uv sync --locked --group docs --no-dev
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
@@ -24,6 +24,3 @@ sphinx:
 formats:
    - pdf
    - epub
-
-# NOTE: We need to use older version of sphinx otherwise bullet points won't be rendered correctly
-# on RTD using rtd theme.

CHANGES.rst

@@ -2655,7 +2655,7 @@ Compute
 ~~~~~~~
 
 - [ARM] Support OS disk size definition on node creation (#1196)
-  [Vojta Bartoš]
+  [Vojta Bartoš]
 
 - [Digital Ocean] Support floating IPs (#1177)
   [Rick van de Loo]

docs/conf.py

@@ -21,11 +21,6 @@
 from sphinx.ext import apidoc
 from sphinx.domains.python import PythonDomain
 
-try:
-    import sphinx_rtd_theme
-except ImportError:
-    sphinx_rtd_theme = None
-
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 BASE_DIR = os.path.abspath(BASE_DIR)
 
@@ -121,13 +116,6 @@
 # a list of builtin themes.
 html_theme = "sphinx_rtd_theme"
 
-if sphinx_rtd_theme:
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-else:
-    html_theme = "default"
-
-
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

docs/development.rst

@@ -51,6 +51,16 @@ If you also work on documentation, add the docs group:
 
 Commit ``uv.lock`` whenever dependency versions change.
 
+Build the HTML documentation with ``uv run tox -e docs``. To also validate the
+PDF and EPUB formats published on Read the Docs, run ``uv run tox -e docs-formats``.
+PDF builds require ``make``, ``latexmk``, ``xindy``, the recommended and extra
+LaTeX packages, and the recommended and TeX Gyre fonts. On Ubuntu, install these with:
+
+.. sourcecode:: bash
+
+    sudo apt-get install make latexmk xindy texlive-latex-recommended \
+        texlive-latex-extra texlive-fonts-recommended tex-gyre
+
 General contribution guidelines
 -------------------------------
 

pyproject.toml

@@ -112,8 +112,8 @@ lint = [
 docs = [
     "rstcheck==6.2.5; python_version >= '3.10'",
     "fasteners",
-    "sphinx_rtd_theme==2.0.0",
-    "sphinx==6.2.1",
+    "sphinx_rtd_theme==3.1.0",
+    "sphinx==8.1.3",
     "pygments>=2.20.0,<3.0.0",
 ]
 mypy = [

tox.ini

@@ -138,6 +138,15 @@ commands = rstcheck --report-level warning ../README.rst
            # TODO: Add -W back when we fix all the warnings in docstrings
            sphinx-build -j auto -b html -d {envtmpdir}/doctrees . _build/html
 
+[testenv:docs-formats]
+basepython = python3.12
+dependency_groups =
+    docs
+changedir = docs
+commands = python ../contrib/generate_provider_feature_matrix_table.py
+           sphinx-build -j auto -b epub -d {envtmpdir}/doctrees-epub . _build/epub
+           sphinx-build -M latexpdf . _build -j auto
+
 [testenv:provider-tables]
 basepython: python3.12
 commands = python ./contrib/generate_provider_feature_matrix_table.py