fix: gate PyPI releases on Sphinx docs build (#6)

Author: rahulkaushal04

.github/workflows/ci.yml

@@ -12,11 +12,6 @@
 # spec-validation    Validates all TOML journal specs and runs the import-time
 #                    benchmark to catch regressions before they reach `main`.
 #
-# docs               Builds the Sphinx documentation with -W (warnings as
-#                    errors).  The generated HTML is uploaded as an artifact
-#                    so reviewers can inspect rendered output without a local
-#                    build.
-#
 # Job dependencies
 # ────────────────
 # All jobs are independent and run in parallel.  There is no `needs:` chain
@@ -122,45 +117,3 @@ jobs:
 
       - name: Benchmark cold import time
         run: python scripts/benchmark_import.py --trials 10 --target-ms 1000
-
-  # ───────────────────────────────────────────────────────────────────────────
-  # Docs build — Sphinx with warnings-as-errors
-  # Catches broken autodoc references, bad cross-links, and rst/md syntax
-  # errors before they reach `main`.  Built HTML is uploaded as an artifact
-  # so reviewers can inspect rendered output without a local build.
-  # ───────────────────────────────────────────────────────────────────────────
-  docs:
-    name: Docs build
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout source
-        uses: actions/checkout@v6
-
-      - name: Set up Python ${{ env.CANONICAL_PYTHON }}
-        uses: actions/setup-python@v6
-        with:
-          python-version: ${{ env.CANONICAL_PYTHON }}
-          cache: pip
-
-      - name: Install package with docs extras
-        # .[docs] installs sphinx, furo, myst-parser, and the package itself
-        # so autodoc can import every module it documents.
-        run: pip install ".[docs]"
-
-      - name: Build documentation
-        # -W turns every Sphinx warning into a build error.
-        # -n (nitpick) flags references to undefined labels or missing members.
-        # --keep-going reports all errors rather than stopping on the first.
-        # READTHEDOCS enables the full intersphinx mapping (matplotlib, numpy,
-        # seaborn) so CI catches broken cross-links before they reach RTD.
-        env:
-          READTHEDOCS: "true"
-        run: sphinx-build -W -n --keep-going -b html docs docs/_build/html
-
-      - name: Upload HTML documentation
-        if: success()
-        uses: actions/upload-artifact@v7
-        with:
-          name: docs-html
-          path: docs/_build/html/
-          retention-days: 14

.github/workflows/release.yml

@@ -11,11 +11,15 @@
 # publish    Builds the source distribution and wheel, then uploads to PyPI
 #            using Trusted Publishing (OIDC — no API token required).
 #
+# docs       Builds the Sphinx documentation with -W (warnings as errors) and
+#            uploads the rendered HTML as a release artifact so each published
+#            version has a corresponding browsable docs snapshot.
+#
 # github-release
 #            Creates a GitHub Release for the tag with auto-generated release
 #            notes drawn from merged pull requests since the previous release.
 #
-# Job order: validate → publish → github-release
+# Job order: validate + docs → publish → github-release
 #
 # References
 # ──────────
@@ -76,15 +80,58 @@ jobs:
         run: python scripts/benchmark_import.py --trials 10 --target-ms 1000
 
   # ───────────────────────────────────────────────────────────────────────────
-  # 2. Build and publish to PyPI
+  # 2. Docs build — Sphinx with warnings-as-errors
+  #    Verifies the documentation builds cleanly against the release commit.
+  #    The rendered HTML is uploaded as a release artifact so each published
+  #    version has a corresponding browsable docs snapshot.
+  # ───────────────────────────────────────────────────────────────────────────
+  docs:
+    name: Docs build
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v6
+
+      - name: Set up Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Install package with docs extras
+        # .[docs] installs sphinx, furo, myst-parser, and the package itself
+        # so autodoc can import every module it documents.
+        run: pip install ".[docs]"
+
+      - name: Build documentation
+        # -W turns every Sphinx warning into a build error.
+        # -n (nitpick) flags references to undefined labels or missing members.
+        # --keep-going reports all errors rather than stopping on the first.
+        # READTHEDOCS enables the full intersphinx mapping (matplotlib, numpy,
+        # seaborn) so CI catches broken cross-links before they reach RTD.
+        env:
+          READTHEDOCS: "true"
+        run: sphinx-build -W -n --keep-going -b html docs docs/_build/html
+
+      - name: Upload HTML documentation
+        if: success()
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: docs/_build/html/
+          retention-days: 90   # keep for the lifetime of the release cycle
+
+  # ───────────────────────────────────────────────────────────────────────────
+  # 4. Build and publish to PyPI
   #    Uses PyPA Trusted Publishing (OIDC) — no API token needed.
   #    Requires a Trusted Publisher entry configured on pypi.org for this
   #    repository / workflow file / environment.
   # ───────────────────────────────────────────────────────────────────────────
   publish:
     name: Build and publish to PyPI
     runs-on: ubuntu-latest
-    needs: validate
+    needs: [validate, docs]
     permissions:
       id-token: write   # required for OIDC Trusted Publishing
     environment:
@@ -119,7 +166,7 @@ jobs:
         # the id-token: write permission and the PyPI Trusted Publisher config.
 
   # ───────────────────────────────────────────────────────────────────────────
-  # 3. Create GitHub Release
+  # 5. Create GitHub Release
   #    Runs only after a successful PyPI publish so the release notes are
   #    never created for a failed upload.
   # ───────────────────────────────────────────────────────────────────────────