Wire Sphinx builds into the RTD config via tox

.readthedocs.yaml

@@ -1,19 +1,29 @@
 ---
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 version: 2
+
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: '3.12'
-
-sphinx:
-  configuration: docs/source/conf.py
-  fail_on_warning: true
-
-python:
-  install:
-  - requirements: dependencies/default/constraints.txt
-  - requirements: dependencies/docs/constraints.txt
-  - path: .
+    python: >-
+      3.12
+  commands:
+  - >-
+    PYTHONWARNINGS=error
+    python3 -Im venv "${READTHEDOCS_VIRTUALENV_PATH}"
+  - >-
+    PYTHONWARNINGS=error
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    pip install tox
+  - >-
+    PYTHONWARNINGS=error
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    tox -e docs --notest -vvvvv
+  - >-
+    PYTHONWARNINGS=error
+    "${READTHEDOCS_VIRTUALENV_PATH}"/bin/python -Im
+    tox -e docs --skip-pkg-install -q
+    --
+    "${READTHEDOCS_OUTPUT}"/html
+    -b html
+    -D language=en

setup.cfg

@@ -65,7 +65,7 @@ show_missing = true
 [tool:pytest]
 python_files = test_*.py *_example.py
 addopts = -rsx --tb=short
-testpaths = docs/source tests
+testpaths = docs tests
 asyncio_mode = auto
 junit_family=xunit2
 filterwarnings =

tox.ini

@@ -26,14 +26,48 @@ allowlist_externals =
     make
 
 [testenv:docs]
+allowlist_externals =
+    git
 extras = docs
 deps =
      --requirement dependencies/docs/requirements.txt
      --constraint dependencies/docs/constraints.txt
 change_dir = docs
-commands = make html
-allowlist_externals =
-    make
+description = Build The Docs with {basepython}
+commands =
+    # Retrieve possibly missing commits:
+    -git fetch --unshallow
+    -git fetch --tags
+
+    # Build the html docs with Sphinx:
+    {envpython} -Im sphinx \
+      -j auto \
+      {tty:--color} \
+      -a \
+      -T \
+      -n \
+      -W --keep-going \
+      -d "{temp_dir}{/}.doctrees" \
+      . \
+      {posargs:"{envdir}{/}docs_out" -b html}
+
+    # Print out the output docs dir and a way to serve html:
+    -{envpython} -c\
+    'import pathlib;\
+    docs_dir = pathlib.Path(r"{envdir}") / "docs_out";\
+    index_file = docs_dir / "index.html";\
+    print("\n" + "=" * 120 +\
+    f"\n\nOpen the documentation with:\n\n\
+    \t$ python3 -Im webbrowser \N\{QUOTATION MARK\}file://\{index_file\}\N\{QUOTATION MARK\}\n\n\
+    To serve docs, use\n\n\
+    \t$ python3 -Im http.server --directory \
+    \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0\n\n" +\
+    "=" * 120)'
+changedir = {toxinidir}{/}docs
+isolated_build = true
+passenv =
+    SSH_AUTH_SOCK
+skip_install = false
 
 [gh-actions]
 python =