From bc147a45f97cbe2e4676999600236eb2d1f2fc12 Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Thu, 16 Jan 2025 10:35:26 +0100
Subject: [PATCH] Only build in RTD and only doctests in CI (#691)

* Only build in RTD and only doctests in CI

* Adjust CI and contributing docs
---
 .github/CONTRIBUTING.md  | 10 ++++++++--
 .github/workflows/ci.yml |  4 ++--
 .readthedocs.yaml        | 21 +++++++++++----------
 tox.ini                  | 19 +++++++------------
 4 files changed, 28 insertions(+), 26 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index b488ed05..53d8b094 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -93,14 +93,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
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5dd2c213..ac4fb547 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -171,7 +171,7 @@ jobs:
 
 
   docs:
-    name: Build docs & run doctests
+    name: Run doctests
     needs: build-package
     runs-on: ubuntu-latest
     steps:
@@ -189,7 +189,7 @@ jobs:
 
       - 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 71410923..d58ce338 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -6,15 +6,16 @@ build:
   tools:
     # Keep version in sync with tox.ini/docs and ci.yml/docs.
     python: "3.13"
-  commands:
-    # Need the tags to calculate the version (sometimes).
-    - git fetch --tags
-    - asdf plugin add uv
-    - asdf install uv latest
-    - asdf global uv latest
+  jobs:
+    create_environment:
+      # Need the tags to calculate the version (sometimes).
+      - git fetch --tags
 
-    - uvx --with tox-uv tox run -e docs-sponsors
-    - uvx --with tox-uv tox run -e docs -- $READTHEDOCS_OUTPUT
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
 
-sphinx:
-  configuration: docs/conf.py
+    build:
+      html:
+        - uvx --with tox-uv tox run -e docs-sponsors
+        - uvx --with tox-uv tox run -e docs-build -- $READTHEDOCS_OUTPUT
diff --git a/tox.ini b/tox.ini
index 7c9aedb1..005c8f20 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,7 +5,7 @@ env_list =
     mypy-pkg,
     py3{8,9,10,11,12,13}-{tests,mypy}
     py3{8,13}-tests-{colorama,be,rich},
-    docs{,-sponsors},
+    docs-{sponsors,doctests},
     coverage-report
 
 
@@ -43,19 +43,19 @@ commands =
     coverage report
 
 
-[testenv:docs]
+[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 {posargs:docs/_build/}html
-    sphinx-build -n -T -W -b doctest -d {envtmpdir}/doctrees docs {posargs: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 \
@@ -64,11 +64,6 @@ commands =
         src \
         docs
 
-[testenv:docs-linkcheck]
-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