Consolidate shared Sphinx infra into 4 workspace packages

.github/workflows/docs.yml

@@ -14,9 +14,6 @@ jobs:
   build:
     runs-on: ubuntu-latest
     environment: docs
-    strategy:
-      matrix:
-        python-version: ['3.14']
     steps:
       - uses: actions/checkout@v6
 
@@ -25,47 +22,45 @@ jobs:
         id: changes
         with:
           filters: |
-            root_docs:
-              - CHANGES
-              - README.*
-            docs:
+            publishable:
+              - 'README.*'
+              - 'CHANGES'
               - 'docs/**'
-              - 'examples/**'
-            python_files:
-              - 'src/gp_sphinx/**/*.py'
-              - pyproject.toml
-              - uv.lock
-
-      - name: Should publish
-        # if: steps.changes.outputs.docs == 'true' || steps.changes.outputs.root_docs == 'true' || steps.changes.outputs.python_files == 'true'
-        run: echo "PUBLISH=$(echo true)" >> $GITHUB_ENV
+              - 'packages/**'
+              - 'scripts/ci/**'
+              - '.github/workflows/docs.yml'
+              - '.github/workflows/tests.yml'
+              - 'pyproject.toml'
+              - 'uv.lock'
+
+      - name: Set up Python 3.14
+        if: steps.changes.outputs.publishable == 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
 
       - name: Install uv
+        if: steps.changes.outputs.publishable == 'true'
         uses: astral-sh/setup-uv@v7
-        if: env.PUBLISH == 'true'
         with:
           enable-cache: true
 
-      - name: Set up Python ${{ matrix.python-version }}
-        if: env.PUBLISH == 'true'
-        run: uv python install ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        if: env.PUBLISH == 'true'
-        run: uv sync --all-extras --dev
+      - name: Install workspace dependencies
+        if: steps.changes.outputs.publishable == 'true'
+        run: uv sync --all-packages --all-extras --group dev
 
       - name: Install just
-        if: env.PUBLISH == 'true'
+        if: steps.changes.outputs.publishable == 'true'
         uses: extractions/setup-just@v3
 
-      - name: Print python versions
-        if: env.PUBLISH == 'true'
+      - name: Print Python versions
+        if: steps.changes.outputs.publishable == 'true'
         run: |
           python -V
           uv run python -V
 
       - name: Cache sphinx fonts
-        if: env.PUBLISH == 'true'
+        if: steps.changes.outputs.publishable == 'true'
         uses: actions/cache@v5
         with:
           path: ~/.cache/sphinx-fonts
@@ -74,32 +69,31 @@ jobs:
             sphinx-fonts-
 
       - name: Build documentation
-        if: env.PUBLISH == 'true'
-        run: |
-          cd docs && just html
+        if: steps.changes.outputs.publishable == 'true'
+        run: uv run sphinx-build -W -b html docs docs/_build/html
 
       - name: Configure AWS Credentials
-        if: env.PUBLISH == 'true'
+        if: steps.changes.outputs.publishable == 'true'
         uses: aws-actions/configure-aws-credentials@v6
         with:
           role-to-assume: ${{ secrets.GP_SPHINX_DOCS_ROLE_ARN }}
           aws-region: us-east-1
 
       - name: Push documentation to S3
-        if: env.PUBLISH == 'true'
+        if: steps.changes.outputs.publishable == 'true'
         run: |
           aws s3 sync docs/_build/html "s3://${{ secrets.GP_SPHINX_DOCS_BUCKET }}" \
             --delete --follow-symlinks
 
       - name: Invalidate CloudFront
-        if: env.PUBLISH == 'true'
+        if: steps.changes.outputs.publishable == 'true'
         run: |
           aws cloudfront create-invalidation \
             --distribution-id "${{ secrets.GP_SPHINX_DOCS_DISTRIBUTION }}" \
             --paths "/index.html" "/objects.inv" "/searchindex.js"
 
       - name: Purge cache on Cloudflare
-        if: env.PUBLISH == 'true'
+        if: steps.changes.outputs.publishable == 'true'
         uses: jakejarvis/cloudflare-purge-action@v0.3.0
         env:
           CLOUDFLARE_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+  attestations: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Resolve release metadata
+        id: release
+        run: |
+          python - <<'PY' "${GITHUB_REF_NAME}" >> "${GITHUB_OUTPUT}"
+          import json
+          import pathlib
+          import sys
+
+          sys.path.insert(0, str(pathlib.Path("scripts/ci").resolve()))
+          import package_tools
+
+          metadata = package_tools.release_metadata(sys.argv[1])
+          for key, value in metadata.items():
+              print(f"{key}={value}")
+          PY
+
+      - name: Install workspace dependencies
+        run: uv sync --all-packages --all-extras --group dev
+
+      - name: Validate lockstep versions
+        run: uv run python scripts/ci/package_tools.py check-versions
+
+      - name: Build publishable packages
+        run: |
+          rm -rf dist
+          mkdir -p dist
+          while IFS= read -r package; do
+            uv build --package "$package" --out-dir dist
+          done < <(uv run python scripts/ci/package_tools.py print-packages)
+
+      - name: Validate distributions with twine
+        run: uvx twine check dist/*
+
+      - name: Smoke test publishable packages
+        run: |
+          while IFS= read -r package; do
+            uv run python scripts/ci/package_tools.py smoke "$package" --dist-dir dist
+          done < <(uv run python scripts/ci/package_tools.py print-packages)
+
+      - name: Publish packages
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+          packages-dir: dist/
+          skip-existing: true

.github/workflows/tests.yml

@@ -1,30 +1,33 @@
-name: tests
+name: ci
 
-on: [push, pull_request]
+on:
+  push:
+  pull_request:
 
 jobs:
-  build:
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
-
+  qa:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
 
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
-      - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        run: uv sync --all-extras --dev
+      - name: Install workspace dependencies
+        run: uv sync --all-packages --all-extras --group dev
 
-      - name: Print python and pytest versions
+      - name: Print Python versions
         run: |
           python -V
           uv run python -V
@@ -36,49 +39,118 @@ jobs:
       - name: Format with ruff format
         run: uv run ruff format . --check
 
-      - name: Lint with mypy
+      - name: Type check with mypy
         run: uv run mypy .
 
+      - name: Validate package runtime versions
+        if: matrix.python-version == '3.14'
+        run: uv run python scripts/ci/package_tools.py check-versions
+
       - name: Test with pytest
-        run: uv run py.test --cov=./ --cov-report=xml
+        if: matrix.python-version != '3.14'
+        run: uv run pytest
+
+      - name: Test with pytest and coverage
+        if: matrix.python-version == '3.14'
+        run: uv run pytest --cov=./ --cov-report=xml
 
       - uses: codecov/codecov-action@v6
+        if: matrix.python-version == '3.14'
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
-  release:
+  docs:
     runs-on: ubuntu-latest
-    needs: build
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-    permissions:
-      id-token: write
-      attestations: write
+    needs: qa
+    steps:
+      - uses: actions/checkout@v6
 
-    strategy:
-      matrix:
-        python-version: ['3.14']
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install workspace dependencies
+        run: uv sync --all-packages --all-extras --group dev
 
+      - name: Build documentation with warnings as errors
+        run: uv run sphinx-build -W -b html docs docs/_build/html
+
+  packages:
+    runs-on: ubuntu-latest
+    needs: qa
     steps:
       - uses: actions/checkout@v6
 
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
       - name: Install uv
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
 
-      - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
+      - name: Install workspace dependencies
+        run: uv sync --all-packages --all-extras --group dev
 
-      - name: Install dependencies
-        run: uv sync --all-extras --dev
+      - name: Validate package runtime versions
+        run: uv run python scripts/ci/package_tools.py check-versions
 
-      - name: Build package
-        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-        run: uv build
+      - name: Build all workspace packages
+        run: uv build --all-packages --out-dir dist --clear
 
-      - name: Publish package
-        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Validate distributions with twine
+        run: uvx twine check dist/*
+
+      - name: Upload package distributions
+        uses: actions/upload-artifact@v7
         with:
-          attestations: true
-          skip-existing: true
+          name: dist
+          path: dist/
+
+  smoke:
+    runs-on: ubuntu-latest
+    needs: packages
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - root-install
+          - gp-sphinx
+          - sphinx-gptheme
+          - sphinx-fonts
+          - sphinx-argparse-neo
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Download package distributions
+        if: matrix.target != 'root-install'
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Smoke test root bootstrap install
+        if: matrix.target == 'root-install'
+        run: python scripts/ci/package_tools.py smoke root-install
+
+      - name: Smoke test built package artifact
+        if: matrix.target != 'root-install'
+        run: python scripts/ci/package_tools.py smoke "${{ matrix.target }}" --dist-dir dist

AGENTS.md

@@ -38,11 +38,10 @@ This project uses:
 
 ```bash
 # Install dependencies
-uv pip install --editable .
-uv pip sync
+uv sync --all-packages
 
 # Install with development dependencies
-uv pip install --editable . -G dev
+uv sync --all-packages --all-extras --group dev
 ```
 
 ### Running Tests