Add versioned documentation publishing and navigation

.github/workflows/doc.yml

@@ -8,7 +8,7 @@ on:  # yamllint disable-line rule:truthy
   pull_request:
 
 permissions:
-  contents: write  # gh-pages push
+  contents: read
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ startsWith(github.ref, 'refs/pull/') || github.run_number }}  # yamllint disable-line
@@ -20,6 +20,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          fetch-depth: 0
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
@@ -47,10 +49,3 @@ jobs:
         working-directory: ./docs
         run: |
           uv run --no-project sphinx-build -M doctest "source" "build" -W --keep-going
-
-      - name: Push documentation to gh-pages
-        if: github.event_name == 'push'
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.11'
+  jobs:
+    post_checkout:
+      - if [ "$(git rev-parse --is-shallow-repository)" = true ]; then git fetch --unshallow; fi
+      - git fetch --tags
+    post_install:
+      - python -m pip install uv
+      - python -m uv pip install --python "$READTHEDOCS_VIRTUALENV_PATH/bin/python" --torch-backend=cpu --group=doc .
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true

docs/README.md

@@ -0,0 +1,27 @@
+# Documentation
+
+Install the package and documentation dependencies, then build HTML and run doctests with warnings treated as errors:
+
+```bash
+uv pip install --torch-backend=cpu --group=doc .
+uv run --no-project sphinx-build -M html docs/source docs/build -W --keep-going
+uv run --no-project sphinx-build -M doctest docs/source docs/build -W --keep-going
+```
+
+## Read the Docs
+
+[`.readthedocs.yaml`](../.readthedocs.yaml) builds the existing Sphinx site on Python 3.11 with CPU-only PyTorch and the `doc` dependency group. It fetches Git history and tags so `setuptools-scm` can identify the installed package version. Read the Docs handles hosting and its built-in version menu; no custom archive, version index, or selector is required. GitHub Actions continues to validate HTML and doctests without publishing to GitHub Pages.
+
+The Sphinx configuration uses `READTHEDOCS_CANONICAL_URL` for canonical page URLs and the theme's copied-source URLs, including release documentation and pull request previews. Local builds work without this environment variable.
+
+## Maintainer setup
+
+1. Import this repository into the organization's Read the Docs account and enable its GitHub integration, using `.readthedocs.yaml` as the configuration file.
+2. Build `latest` from `main` and verify the generated API pages and version menu. Enable pull request builds if preview documentation is desired.
+3. Activate supported release versions. Read the Docs provides `stable` for the greatest stable semantic version and `latest` for the default branch; configure the default documentation version and version-activation rules in the dashboard.
+4. Plan older-release builds separately: immutable tags predating `.readthedocs.yaml` do not inherit configuration from `main`. Backport documentation configuration to maintained release branches where appropriate, and validate each historical version before advertising it. Do not move existing release tags.
+5. Once the hosted site and its final URL are verified, update public documentation links and arrange redirects from the existing GitHub Pages URLs. This change stops Pages publication but leaves the previously published site intact during the migration.
+
+Account setup, version activation, preview builds, and redirects require maintainer access. A local Sphinx build verifies the documentation but cannot verify these hosted settings.
+
+See the Read the Docs guides for [version management](https://docs.readthedocs.com/platform/stable/versions.html), [build customization](https://docs.readthedocs.com/platform/stable/build-customization.html), and the [version menu](https://docs.readthedocs.com/platform/stable/flyout-menu.html).

docs/source/conf.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import importlib
+import os
 from datetime import date
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as package_version
@@ -42,6 +43,7 @@
     "accent_color": "green",
     "github_url": "https://github.com/NVIDIA/structured-data-models",
 }
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 autosummary_generate = True