diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml index 4579501b2..fab8e28ed 100644 --- a/.github/workflows/build_and_test.yml +++ b/.github/workflows/build_and_test.yml @@ -4,8 +4,26 @@ 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: @@ -13,6 +31,11 @@ on: 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: diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 000000000..74c4d9445 --- /dev/null +++ b/.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 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index e5fdde3a2..e4c602956 100644 --- a/.github/workflows/publish.yml +++ b/.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 \ No newline at end of file + id-token: write \ No newline at end of file