1.0.0

.github/workflows/docs.yml

@@ -1,49 +1,33 @@
-name: "Publish Docs"
+name: "Docs"
 
 on:
+  pull_request:
   push:
     branches:
       - main
 
 jobs:
   docs:
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-      - name: Install uv
-        run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      # uv manages its own interpreter (UV_MANAGED_PYTHON=1 in the Makefile).
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v4
 
-      - name: Build documentation with Makefile
-        env:
-          PYTHON_VERSION: "3.11"
-        run: |
-          uv python install "$PYTHON_VERSION"
-          make docs PYTHON_VERSION="$PYTHON_VERSION"
+      - name: Build docs (warnings are errors)
+        run: make docs
 
-      - name: Clone gh-pages branch
-        run: |
-          git clone --branch gh-pages --single-branch \
-            "https://github.com/${{ github.repository }}.git" gh-pages
-          rm -rf gh-pages/*
-          cp -r docs/_build/* gh-pages/
+      - name: Run documentation snippet tests
+        run: make docs-test
 
-      - name: Commit documentation changes
-        run: |
-          cd gh-pages
-          touch .nojekyll
-          git config --local user.email "action@github.com"
-          git config --local user.name "GitHub Action"
-          git add .
-          git commit -m "Update documentation" || echo "No changes to commit"
+      - name: Upload built site
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/_build
 
-      - name: Push changes
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          cd gh-pages
-          git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" gh-pages
+      # ADD THIS BACK IN LATER -- SOME LINKS WILL NOT RESOLVE RIGHT NOW
+      # - name: Check external links
+      #   run: make docs-linkcheck

.github/workflows/release.yml

@@ -0,0 +1,188 @@
+name: Release GerryChain
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag, for example v1.0.0
+        type: string
+        required: true
+      upload_to:
+        description: Upload destination
+        type: choice
+        required: true
+        default: testpypi
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and test distributions
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Check out release tag
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.tag }}
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.12.1"
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Validate release tag
+        id: release
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          if [[ "$GITHUB_REF" != "refs/heads/main" ]]; then
+            echo "Dispatch this workflow from the main branch, not $GITHUB_REF_NAME."
+            exit 1
+          fi
+          project_version="$(uv version --short)"
+          if [[ "$RELEASE_TAG" != "v$project_version" ]]; then
+            echo "Tag $RELEASE_TAG does not match project version $project_version."
+            exit 1
+          fi
+          if ! git show-ref --verify --quiet "refs/tags/$RELEASE_TAG"; then
+            echo "$RELEASE_TAG is not a tag in this repository."
+            exit 1
+          fi
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor HEAD origin/main; then
+            echo "The tagged commit is not on the main branch."
+            exit 1
+          fi
+          echo "version=$project_version" >> "$GITHUB_OUTPUT"
+          echo "RELEASE_VERSION=$project_version" >> "$GITHUB_ENV"
+
+      - name: Run tests
+        run: uv run --locked pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke test wheel
+        run: >-
+          uv run --isolated --no-project --with dist/*.whl python -c
+          'import os; from importlib.metadata import version;
+          from gerrychain.examples import gerrymandria;
+          assert version("gerrychain") == os.environ["RELEASE_VERSION"];
+          assert len(gerrymandria().nodes) == 64'
+
+      - name: Smoke test source distribution
+        run: >-
+          uv run --isolated --no-project --with dist/*.tar.gz python -c
+          'import os; from importlib.metadata import version;
+          from gerrychain.examples import gerrymandria;
+          assert version("gerrychain") == os.environ["RELEASE_VERSION"];
+          assert len(gerrymandria().nodes) == 64'
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  testpypi:
+    name: Publish and verify on TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/gerrychain/
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      RELEASE_VERSION: ${{ needs.build.outputs.version }}
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.12.1"
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish to TestPyPI
+        run: >-
+          uv publish --trusted-publishing always
+          --publish-url https://test.pypi.org/legacy/
+          --check-url https://test.pypi.org/simple/
+          dist/*
+
+      - name: Install dependencies from PyPI
+        run: |
+          uv venv --python 3.13 "$RUNNER_TEMP/testpypi-venv"
+          uv pip install --python "$RUNNER_TEMP/testpypi-venv/bin/python" dist/*.whl
+
+      - name: Install wheel from TestPyPI
+        run: |
+          for attempt in {1..10}; do
+            if uv pip install \
+              --python "$RUNNER_TEMP/testpypi-venv/bin/python" \
+              --reinstall-package gerrychain \
+              --no-deps \
+              --default-index https://test.pypi.org/simple/ \
+              "gerrychain==$RELEASE_VERSION"; then
+              exit 0
+            fi
+            if [[ "$attempt" == 10 ]]; then
+              echo "TestPyPI did not make gerrychain $RELEASE_VERSION available in time."
+              exit 1
+            fi
+            sleep 15
+          done
+
+      - name: Smoke test TestPyPI installation
+        run: >-
+          "$RUNNER_TEMP/testpypi-venv/bin/python" -c
+          'import os; from importlib.metadata import version;
+          from gerrychain.examples import gerrymandria;
+          assert version("gerrychain") == os.environ["RELEASE_VERSION"];
+          assert len(gerrymandria().nodes) == 64'
+
+  pypi:
+    name: Publish to PyPI
+    needs: [build, testpypi]
+    if: ${{ inputs.upload_to == 'pypi' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gerrychain/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.12.1"
+
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        run: >-
+          uv publish --trusted-publishing always
+          --check-url https://pypi.org/simple/
+          dist/*

.gitignore

@@ -59,6 +59,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/_generated/
 _build
 
 # PyBuilder
@@ -87,3 +88,15 @@ TODO.md
 # Environment items
 .env
 .envrc
+
+# Profiling data
+*.prof
+docs/jupyter_execute/
+
+# Sample data copied next to a tutorial so it can be run interactively from docs/user/.
+# The committed copy lives in docs/_static/ and is staged automatically by
+# docs/_refresh_notebooks.py, so this local duplicate must never be committed.
+docs/user/PA_VTDs.json
+
+# Written by docs/user/data.ipynb when it runs; not a source file.
+docs/user/PA_output.jsonl

.pre-commit-config.yaml

@@ -1,6 +1,13 @@
 repos:
   - repo: local
     hooks:
+      - id: clear-notebook-outputs
+        name: Clear notebook outputs
+        entry: >-
+          uv run --no-default-groups --group docs-exec
+          python docs/_clear_notebook_outputs.py
+        language: system
+        files: ^docs/user/.*\.ipynb$
       - id: make-format
         name: Run `make check` (format + lint)
         entry: make check