Fix RTD build (#1396)

* Fix RTD build

* Update contributing guide

Author: hynek

.github/CONTRIBUTING.md

@@ -98,14 +98,20 @@ $ tox run -e docs-watch
 
 This will build the documentation, watch for changes, and rebuild it whenever you save a file.
 
-To just build the documentation and run doctests, use:
+To just build the documentation and exit immediately use:
 
 ```console
-$ tox run -e docs
+$ tox run -e docs-build
 ```
 
 You will find the built documentation in `docs/_build/html`.
 
+To run doctests:
+
+```console
+$ tox run -e docs-doctests
+```
+
 
 ## Code
 

.github/workflows/ci.yml

@@ -172,7 +172,7 @@ jobs:
         if: ${{ failure() }}
 
   docs:
-    name: Build docs & run doctests
+    name: Run doctests & render changelog
     runs-on: ubuntu-latest
     needs: build-package
     steps:
@@ -188,7 +188,7 @@ jobs:
           python-version: "3.13"
       - uses: hynek/setup-cached-uv@v2
 
-      - run: uvx --with=tox-uv tox run -e docs,changelog
+      - run: uvx --with=tox-uv tox run -e docs-doctests,changelog
 
   pyright:
     name: Check types using pyright

.readthedocs.yaml

@@ -7,18 +7,15 @@ build:
     # Keep version in sync with tox.ini/docs and ci.yml/docs.
     python: "3.13"
   jobs:
-    # Need the tags to calculate the version (sometimes).
-    post_checkout:
+    create_environment:
+      # Need the tags to calculate the version (sometimes).
       - git fetch --tags
 
-    # Replace versions in sponsor URLs.
-    pre_build:
-      - python -Im pip install tox-uv
-      - python -Im tox run -e docs-sponsors
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
 
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+    build:
+      html:
+        - uvx --with tox-uv tox run -e docs-sponsors
+        - uvx --with tox-uv tox run -e docs-build -- $READTHEDOCS_OUTPUT

tox.ini

@@ -6,7 +6,7 @@ env_list =
     py3{10,11,12,13}-mypy,
     pypy3-tests,
     pyright,
-    docs{,-sponsors},
+    docs-{sponsors,doctests},
     changelog,
     coverage-report
 
@@ -64,19 +64,19 @@ pass_env =
 commands = pytest --codspeed -n auto bench/test_benchmarks.py
 
 
-[testenv:docs]
-# Keep base_python in-sync with ci.yml/docs and .readthedocs.yaml.
+[testenv:docs-{build,doctests,linkcheck}]
+# Keep base_python in sync with ci.yml/docs and .readthedocs.yaml.
 base_python = py313
 extras = docs
 commands =
-    sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
-    sphinx-build -n -T -W -b doctest -d {envtmpdir}/doctrees docs docs/_build/html
-
+    build: sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs {posargs:docs/_build/}html
+    doctests: sphinx-build -n -T -W -b doctest -d {envtmpdir}/doctrees docs {posargs:docs/_build/}html
+    linkcheck: sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html
 
 [testenv:docs-watch]
 package = editable
-base_python = {[testenv:docs]base_python}
-extras = {[testenv:docs]extras}
+base_python = {[testenv:docs-build]base_python}
+extras = {[testenv:docs-build]extras}
 deps = watchfiles
 commands =
     watchfiles \
@@ -85,14 +85,6 @@ commands =
         src \
         docs
 
-
-[testenv:docs-linkcheck]
-package = editable
-base_python = {[testenv:docs]base_python}
-extras = {[testenv:docs]extras}
-commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/html
-
-
 [testenv:docs-sponsors]
 description = Ensure sponsor logos are up to date.
 deps = cogapp