Update documentation build

.github/workflows/ci.yml

@@ -128,6 +128,48 @@ jobs:
         run: |
           uv run pytest --cov-fail-under=48
 
+  docs:
+    name: Docs (build + linkcheck)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Sync docs dependency group
+        run: |
+          uv sync --locked --group docs --no-dev
+
+      - name: Build HTML docs (warnings are errors)
+        run: |
+          uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+
+      - name: Link check (non-blocking)
+        continue-on-error: true
+        run: |
+          uv run sphinx-build -b linkcheck docs docs/_build/linkcheck
+
+      - name: Upload rendered HTML artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html-${{ github.sha }}
+          path: docs/_build/html
+          if-no-files-found: error
+
+      - name: Upload linkcheck report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-linkcheck-${{ github.sha }}
+          path: docs/_build/linkcheck
+          if-no-files-found: warn
+
   package-briefcase-zip:
     name: Package Briefcase ZIP (Windows)
     runs-on: windows-latest

.readthedocs.yaml

@@ -3,15 +3,19 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
   jobs:
     pre_install:
       - python -m pip install --upgrade pip
       - python -m pip install uv
     install:
-      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv pip install -r docs/requirements.txt
-      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv pip install .
+      # Install the project plus the "docs" dependency group (pyproject.toml
+      # -> [dependency-groups].docs) into the RTD-managed virtualenv, honoring
+      # uv.lock for reproducibility. No dev/build groups are needed to render docs.
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --locked --group docs --no-dev
 
 sphinx:
   configuration: docs/conf.py
-  fail_on_warning: false
+  # Treat Sphinx warnings as errors. Known harmless warnings are suppressed
+  # via `suppress_warnings` in docs/conf.py rather than relaxed here.
+  fail_on_warning: true

docs/conf.py

@@ -8,17 +8,28 @@
 project = "Clinical DBS Annotator"
 author = "Lucia Poma"
 release = metadata.version(_DIST_NAME)
+version = ".".join(release.split(".")[:2])
 copyright = f"2025-{datetime.now().year}, {author}"
 
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# Known, non-actionable warnings that would otherwise fail `-W` builds.
+# `image.not_readable` covers screenshots under docs/_static/ that are
+# re-generated from the running app and not committed to git (tracked in
+# the documentation strategy, P3: screenshot pipeline).
+suppress_warnings = [
+    "image.not_readable",
+]
+
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
 
@@ -30,3 +41,14 @@
     "sticky_navigation": True,
     "navigation_depth": 3,
 }
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# `linkcheck` tuning: timeout aggressive, retry transient failures, and ignore
+# anchor-only link failures on sites that rewrite fragments (common on GitHub).
+linkcheck_timeout = 15
+linkcheck_retries = 2
+linkcheck_anchors = False
+linkcheck_ignore: list[str] = []