From 6c2264e20384a39fb69c810f3fcfe4377b237bc9 Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Sat, 22 Feb 2025 09:43:10 +0100
Subject: [PATCH] Split docs targets for faster builds (#194)

* Split docs targets for faster builds

* Kill copypasta

* Try using uv's Python
---
 .github/workflows/ci.yml |  8 ++------
 .readthedocs.yaml        | 23 +++++++++--------------
 tox.ini                  | 19 ++++++++++---------
 3 files changed, 21 insertions(+), 29 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2e9229c..7320cce 100644
--- a/.github/workflows/ci.yml
+++ b/.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:
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index f0f77a0..e08ea38 100644
--- a/.readthedocs.yaml
+++ b/.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.
-    post_checkout:
+    create_environment:
+      # Need the tags to calculate the version (sometimes).
       - git fetch --tags
 
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
 
-submodules:
-  include: all
-
-sphinx:
-  configuration: docs/conf.py
+    build:
+      html:
+        - uvx --with tox-uv tox run -e docs-build -- $READTHEDOCS_OUTPUT
diff --git a/tox.ini b/tox.ini
index b5f3745..6faa52c 100644
--- a/tox.ini
+++ b/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]
-description = Build docs and run doctests.
-# Keep base_python in-sync with .readthedocs.yaml and ci.yml/docs.
+[testenv:docs-{build,doctests,linkcheck}]
+# Keep base_python in sync with .readthedocs.yaml.
 base_python = py313
 extras = docs
 commands =
-    python -m doctest README.md
-    sphinx-build -W -n -b html -d {envtmpdir}/doctrees docs docs/_build/html
-    sphinx-build -W -n -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: python -m doctest README.md
+    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 \