Split docs targets for faster builds (#194)

* Split docs targets for faster builds

* Kill copypasta

* Try using uv's Python

.github/workflows/ci.yml

@@ -201,7 +201,7 @@ jobs:
 
 
   docs:
-    name: Build docs & run doctests
+    name: Run doctests
     needs: build-package
     runs-on: ubuntu-latest
     steps:
@@ -211,15 +211,11 @@ jobs:
           name: Packages
           path: dist
       - run: tar xf dist/*.tar.gz --strip-components=1
-      - uses: actions/setup-python@v5
-        with:
-          # Keep in sync with tox.ini/docs & .readthedocs.yaml
-          python-version: "3.13"
       - uses: hynek/setup-cached-uv@v2
 
       - run: >
           uvx --with tox-uv
-          tox run -e docs
+          tox run -e docs-doctests
 
 
   install-dev:

.readthedocs.yaml

@@ -4,22 +4,17 @@ version: 2
 build:
   os: ubuntu-lts-latest
   tools:
-    # Keep version in sync with tox.ini/docs and ci.yml/docs.
+    # Keep version in sync with tox.ini/docs.
     python: "3.13"
   jobs:
-    # Need the tags to calculate the version.
+    create_environment:
-    post_checkout:
+      # Need the tags to calculate the version (sometimes).
       - git fetch --tags
 
-python:
+      - asdf plugin add uv
-  install:
+      - asdf install uv latest
-    - method: pip
+      - asdf global uv latest
-      path: .
-      extra_requirements:
-        - docs
 
-submodules:
+    build:
-  include: all
+      html:
-
+        - uvx --with tox-uv tox run -e docs-build -- $READTHEDOCS_OUTPUT
-sphinx:
-  configuration: docs/conf.py

tox.ini

@@ -7,7 +7,7 @@ env_list =
     py312-bindings-main,
     pypy3-tests,
     system-argon2,
-    docs,
+    docs-doctests,
     coverage-report
 
 
@@ -81,20 +81,21 @@ deps = mypy
 commands = mypy src
 
 
-[testenv:docs]
+[testenv:docs-{build,doctests,linkcheck}]
-description = Build docs and run doctests.
+# Keep base_python in sync with .readthedocs.yaml.
-# Keep base_python in-sync with .readthedocs.yaml and ci.yml/docs.
 base_python = py313
 extras = docs
 commands =
-    python -m doctest README.md
+    build: sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs {posargs:docs/_build/}html
-    sphinx-build -W -n -b html -d {envtmpdir}/doctrees docs docs/_build/html
+    doctests: python -m doctest README.md
-    sphinx-build -W -n -b doctest -d {envtmpdir}/doctrees docs 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}
+base_python = {[testenv:docs-build]base_python}
-extras = {[testenv:docs]extras}
+extras = {[testenv:docs-build]extras}
 deps = watchfiles
 commands =
     watchfiles \