Ci/factor out docs workflow

.github/workflows/build_and_test.yml

@@ -4,15 +4,38 @@ on:
   push:
     branches:
       - '**'
+    paths-ignore:
+      - 'python/docs/**'
+      - 'doc_resources/**'
+      - 'Doxyfile'
+      - '**/*.md'
+      - '.github/workflows/build_docs.yml'
   pull_request:
+    paths-ignore:
+      - 'python/docs/**'
+      - 'doc_resources/**'
+      - 'Doxyfile'
+      - '**/*.md'
+      - '.github/workflows/build_docs.yml'
   workflow_call:
+    inputs:
+      minimal:
+        description: 'Build only the ubuntu-latest / python-3.11 wheel; skip C++ tests, Windows, macOS, and wheel tests.'
+        required: false
+        type: boolean
+        default: false
   workflow_dispatch:
     inputs:
       full_matrix:
         description: 'Run full OS and Python matrix'
         required: false
         type: boolean
         default: false
+      minimal:
+        description: 'Build only the ubuntu-latest / python-3.11 wheel; skip C++ tests, Windows, macOS, and wheel tests.'
+        required: false
+        type: boolean
+        default: false
 
 concurrency:
   group: build-${{ github.ref }}
@@ -34,7 +57,10 @@ jobs:
           # Mac available to the maintainer). Intel macOS support is paused
           # pending a reproducer or an upstream fix. Re-add "macos-15-intel"
           # below when ready to revisit.
-          if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/develop" || "${{ github.ref }}" == refs/tags/* || "${{ inputs.full_matrix }}" == "true" || "${{ github.event.pull_request.base.ref }}" == "develop" || "${{ github.event.pull_request.base.ref }}" == "main" ]]; then
+          if [[ "${{ inputs.minimal }}" == "true" ]]; then
+            echo 'os=["ubuntu-latest"]' >> $GITHUB_OUTPUT
+            echo 'python_versions=["3.11"]' >> $GITHUB_OUTPUT
+          elif [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/develop" || "${{ github.ref }}" == refs/tags/* || "${{ inputs.full_matrix }}" == "true" || "${{ github.event.pull_request.base.ref }}" == "develop" || "${{ github.event.pull_request.base.ref }}" == "main" ]]; then
             echo 'os=["ubuntu-latest","macos-14"]' >> $GITHUB_OUTPUT
             echo 'python_versions=["3.9","3.10","3.11","3.12","3.13"]' >> $GITHUB_OUTPUT
           else
@@ -44,6 +70,7 @@ jobs:
 
   test_cpp_unix:
     name: C++ tests on ${{ matrix.os }}
+    if: ${{ inputs.minimal != true }}
     needs: [set_matrix]
     runs-on: ${{ matrix.os }}
     strategy:
@@ -107,6 +134,7 @@ jobs:
 
   test_cpp_windows:
     name: C++ tests on Windows
+    if: ${{ inputs.minimal != true }}
     runs-on: windows-latest
     env:
       CONDA_PKGS_DIRS: ${{ github.workspace }}\conda_pkgs
@@ -275,7 +303,8 @@ jobs:
           if-no-files-found: error
 
   build_windows_wheels:
-    name: Windows Python-${{ matrix.python-version }} wheels 
+    name: Windows Python-${{ matrix.python-version }} wheels
+    if: ${{ inputs.minimal != true }}
     runs-on: windows-latest
     env:
       CONDA_PKGS_DIRS: ${{ github.workspace }}\conda_pkgs
@@ -338,6 +367,7 @@ jobs:
 
   test_wheels_linux_macos:
     name: Test wheels on ${{ matrix.os }} / py${{ matrix.python-version }}
+    if: ${{ inputs.minimal != true }}
     needs: [set_matrix, build_macos_ubuntu_wheels]
     runs-on: ${{ matrix.os }}
     strategy:
@@ -371,6 +401,7 @@ jobs:
 
   test_wheels_windows:
     name: Test wheel on windows-${{ matrix.python-version }}
+    if: ${{ inputs.minimal != true }}
     needs: [build_windows_wheels]
     runs-on: windows-latest
     strategy:

.github/workflows/build_docs.yml

@@ -0,0 +1,152 @@
+name: Build and deploy documentation 📝
+
+on:
+  workflow_call:
+    # When called from publish.yml, the caller's build_and_test job has
+    # already produced the wheel artifact this workflow needs. The internal
+    # build_and_test job below is skipped in that case.
+    inputs:
+      deploy:
+        description: 'Deploy to GitHub Pages after building'
+        required: false
+        type: boolean
+        default: true
+  workflow_dispatch:
+    inputs:
+      deploy:
+        description: 'Deploy to GitHub Pages after building'
+        required: false
+        type: boolean
+        default: true
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_and_test:
+    name: Build wheel (for docs)
+    # Only run when triggered manually. workflow_call invocations assume the
+    # caller already ran build_and_test in the same workflow run, so the
+    # wheel artifact is already available.
+    if: github.event_name == 'workflow_dispatch'
+    uses: ./.github/workflows/build_and_test.yml
+    with:
+      # Docs only need the ubuntu-latest / python-3.11 wheel; skip the full
+      # OS/Python matrix and the wheel/C++ test jobs.
+      minimal: true
+
+  build_docs:
+    name: Build docs
+    needs: [build_and_test]
+    # `build_and_test` is skipped when invoked via workflow_call; treat that
+    # as success so build_docs runs in both modes.
+    if: |
+      always() &&
+      (needs.build_and_test.result == 'success' || needs.build_and_test.result == 'skipped')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # gitpython (used by python/docs/source/conf.py to derive version)
+          # needs the full history; the default depth=1 leaves it unable to
+          # resolve HEAD's commit object on some refs.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Compute build metadata
+        id: meta
+        run: |
+          SHA=$(git rev-parse HEAD)
+          SHORT=$(git rev-parse --short HEAD)
+          DATE=$(date -u +'%Y-%m-%d %H:%M UTC')
+          echo "sha=$SHA"          >> "$GITHUB_OUTPUT"
+          echo "short=$SHORT"      >> "$GITHUB_OUTPUT"
+          echo "date=$DATE"        >> "$GITHUB_OUTPUT"
+          echo "Build metadata: $SHORT ($SHA) at $DATE"
+
+      - name: Install system dependencies (Doxygen)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+
+      - name: Fetch doxygen-awesome-css
+        run: |
+          curl -sSL https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v2.3.4.tar.gz | tar -xz
+          mv doxygen-awesome-css-2.3.4 doxygen-awesome-css
+
+      - name: Build C++ docs (Doxygen)
+        env:
+          PROJECT_NUMBER: "${{ steps.meta.outputs.short }} (${{ steps.meta.outputs.date }})"
+        run: |
+          mkdir -p build/docs/cpp site
+          # Append PROJECT_NUMBER override via stdin; Doxygen reads stdin
+          # config when invoked with `-` and merges with the file.
+          (cat Doxyfile; echo "PROJECT_NUMBER = $PROJECT_NUMBER") | doxygen -
+          mv build/docs/cpp site/cpp
+
+      - name: Install Python deps for Sphinx
+        # The bertini2 wheel bundles the eigenpy C++ libraries it links
+        # against; no Python `eigenpy` install is required to import bertini
+        # for sphinx autodoc.
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+            sphinx sphinx-rtd-theme sphinxcontrib-bibtex gitpython \
+            scikit-build-core build numpy
+
+      - name: Download built wheel
+        uses: actions/download-artifact@v5
+        with:
+          name: wheels-ubuntu-latest-3.11
+          path: dist/
+
+      - name: Install bertini from built wheel
+        run: pip install --no-index --find-links dist/ bertini2
+
+      - name: Build Python docs (Sphinx)
+        working-directory: python/docs
+        env:
+          BERTINI_GIT_SHA: ${{ steps.meta.outputs.sha }}
+          BERTINI_BUILD_DATE: ${{ steps.meta.outputs.date }}
+        run: |
+          sphinx-build -b html -W --keep-going source ../../site/python
+
+      - name: Add landing page
+        env:
+          COMMIT_SHA: ${{ steps.meta.outputs.sha }}
+          COMMIT_SHORT: ${{ steps.meta.outputs.short }}
+          BUILD_DATE: ${{ steps.meta.outputs.date }}
+        run: |
+          sed \
+            -e "s|__COMMIT_SHA__|${COMMIT_SHA}|g" \
+            -e "s|__COMMIT_SHORT__|${COMMIT_SHORT}|g" \
+            -e "s|__BUILD_DATE__|${BUILD_DATE}|g" \
+            doc_resources/landing/index.html > site/index.html
+          cp doc_resources/landing/style.css site/style.css
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy_docs:
+    name: Deploy to GitHub Pages
+    needs:
+      - build_docs
+    if: needs.build_docs.result == 'success' && inputs.deploy
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -143,109 +143,12 @@ jobs:
           files: |
             dist/*.*
 
-  build_docs:
-    name: Build docs
+  build_and_deploy_docs:
+    name: Build and deploy docs
     if: needs.check_version.outputs.is_prerelease == 'false'
     needs: [check_version, build_and_test]
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          # gitpython (used by python/docs/source/conf.py to derive version)
-          # needs the full history; the default depth=1 leaves it unable to
-          # resolve HEAD's commit object on some refs.
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Compute build metadata
-        id: meta
-        run: |
-          SHA=$(git rev-parse HEAD)
-          SHORT=$(git rev-parse --short HEAD)
-          DATE=$(date -u +'%Y-%m-%d %H:%M UTC')
-          echo "sha=$SHA"          >> "$GITHUB_OUTPUT"
-          echo "short=$SHORT"      >> "$GITHUB_OUTPUT"
-          echo "date=$DATE"        >> "$GITHUB_OUTPUT"
-          echo "Build metadata: $SHORT ($SHA) at $DATE"
-
-      - name: Install system dependencies (Doxygen)
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y doxygen graphviz
-
-      - name: Fetch doxygen-awesome-css
-        run: |
-          curl -sSL https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v2.3.4.tar.gz | tar -xz
-          mv doxygen-awesome-css-2.3.4 doxygen-awesome-css
-
-      - name: Build C++ docs (Doxygen)
-        env:
-          PROJECT_NUMBER: "${{ steps.meta.outputs.short }} (${{ steps.meta.outputs.date }})"
-        run: |
-          mkdir -p build/docs/cpp site
-          # Append PROJECT_NUMBER override via stdin; Doxygen reads stdin
-          # config when invoked with `-` and merges with the file.
-          (cat Doxyfile; echo "PROJECT_NUMBER = $PROJECT_NUMBER") | doxygen -
-          mv build/docs/cpp site/cpp
-
-      - name: Install Python deps for Sphinx
-        run: |
-          python -m pip install --upgrade pip
-          pip install \
-            sphinx sphinx-rtd-theme sphinxcontrib-bibtex gitpython \
-            scikit-build-core build numpy eigenpy==3.11.0
-
-      - name: Download built wheel
-        uses: actions/download-artifact@v5
-        with:
-          name: wheels-ubuntu-latest-3.11
-          path: dist/
-
-      - name: Install bertini from built wheel
-        run: pip install --no-index --find-links dist/ bertini2
-
-      - name: Build Python docs (Sphinx)
-        working-directory: python/docs
-        env:
-          BERTINI_GIT_SHA: ${{ steps.meta.outputs.sha }}
-          BERTINI_BUILD_DATE: ${{ steps.meta.outputs.date }}
-        run: |
-          sphinx-build -b html -W --keep-going source ../../site/python
-
-      - name: Add landing page
-        env:
-          COMMIT_SHA: ${{ steps.meta.outputs.sha }}
-          COMMIT_SHORT: ${{ steps.meta.outputs.short }}
-          BUILD_DATE: ${{ steps.meta.outputs.date }}
-        run: |
-          sed \
-            -e "s|__COMMIT_SHA__|${COMMIT_SHA}|g" \
-            -e "s|__COMMIT_SHORT__|${COMMIT_SHORT}|g" \
-            -e "s|__BUILD_DATE__|${BUILD_DATE}|g" \
-            doc_resources/landing/index.html > site/index.html
-          cp doc_resources/landing/style.css site/style.css
-
-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-
-  deploy_docs:
-    name: Deploy to GitHub Pages
-    needs:
-      - build_docs
-    runs-on: ubuntu-latest
+    uses: ./.github/workflows/build_docs.yml
     permissions:
+      contents: read
       pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy
-        id: deployment
-        uses: actions/deploy-pages@v4
+      id-token: write