Run docs deploy without project sync #154
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | |
| # SPDX-License-Identifier: Apache-2.0 | |
| name: Deploy Sphinx documentation to Pages | |
| on: | |
| push: | |
| branches: | |
| - main | |
| # Match release-MAJOR.MINOR exactly. The "Determine doc version + mode" | |
| # step rejects anything else (e.g. release-kit-*), so filter at the | |
| # trigger to avoid burning a runner and the deploy-docs lock. | |
| - 'release-[0-9]*.[0-9]*' | |
| tags: | |
| # Tags gate /stable/ promotion. Branch pushes deploy /vX.Y/ but | |
| # don't touch /stable/ until a corresponding vX.Y.Z tag exists. | |
| # The three-component glob filters out stray v-prefixed tags | |
| # before they consume a runner and hold the deploy-docs lock. | |
| - 'v[0-9]*.[0-9]*.[0-9]*' | |
| workflow_dispatch: | |
| concurrency: | |
| group: deploy-docs | |
| cancel-in-progress: false | |
| env: | |
| PYTHONFAULTHANDLER: "1" # Dump tracebacks on fatal signals (SIGSEGV, SIGABRT, etc.) | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 | |
| with: | |
| lfs: true | |
| # deploy_doc.py uses historical vX.Y.N tags to decide which | |
| # deployed versions are released and eligible for /stable/. | |
| fetch-depth: 0 | |
| - name: Fetch gh-pages branch | |
| # Skip the fetch on a fresh repo where origin has no gh-pages yet | |
| # (deploy_doc.py's orphan path handles that bootstrap case). When the | |
| # branch exists, a fetch failure must abort: continuing on stale | |
| # local state would let `discover_versions()` see an empty tree and | |
| # the subsequent force-push wipe every previously-deployed version. | |
| run: | | |
| if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then | |
| git fetch origin gh-pages:gh-pages | |
| else | |
| echo "origin has no gh-pages branch yet — skipping fetch (bootstrap deploy)" | |
| fi | |
| - name: Determine doc version + mode | |
| # Three trigger flavours: | |
| # - main / release-X.Y / workflow_dispatch on a branch → full | |
| # build, deploy /vX.Y/ (or /latest/) from the branch tip. | |
| # - vX.Y.* tag → tag gates /stable/ promotion. If /vX.Y/ already | |
| # exists on gh-pages (the branch ran first and put it there), | |
| # skip the build and run deploy_doc.py --metadata-only to refresh | |
| # /stable/ + versions.json without regressing /vX.Y/'s content | |
| # to the tagged commit. If /vX.Y/ doesn't exist yet (tag pushed | |
| # before any branch deploy), fall back to a full build from the | |
| # tag commit so the version folder gets populated. | |
| id: dv | |
| run: | | |
| ref="${GITHUB_REF}" | |
| if [[ "$ref" == "refs/heads/main" ]]; then | |
| version="latest" | |
| metadata_only="false" | |
| elif [[ "$ref" =~ ^refs/heads/release-([0-9]+\.[0-9]+)$ ]]; then | |
| version="${BASH_REMATCH[1]}" | |
| metadata_only="false" | |
| elif [[ "$ref" =~ ^refs/tags/v([0-9]+\.[0-9]+)(\.|$) ]]; then | |
| version="${BASH_REMATCH[1]}" | |
| if git rev-parse --verify gh-pages >/dev/null 2>&1 \ | |
| && git ls-tree --name-only "gh-pages" \ | |
| | grep -qE "^v${version}\$"; then | |
| metadata_only="true" | |
| else | |
| metadata_only="false" | |
| fi | |
| else | |
| echo "::error::Unsupported ref '$ref'" | |
| exit 1 | |
| fi | |
| echo "version=$version" >> "$GITHUB_OUTPUT" | |
| echo "metadata_only=$metadata_only" >> "$GITHUB_OUTPUT" | |
| echo "Doc version: $version (metadata_only=$metadata_only)" | |
| - name: Install uv | |
| uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0 | |
| with: | |
| version: "0.11.16" | |
| - name: Set up Python | |
| run: uv python install | |
| - name: Build Warp without CUDA Support | |
| if: steps.dv.outputs.metadata_only != 'true' | |
| run: | | |
| uv run build_lib.py --no-cuda | |
| - name: Build Sphinx documentation | |
| if: steps.dv.outputs.metadata_only != 'true' | |
| run: | | |
| DOC_VERSION=${{ steps.dv.outputs.version }} uv run --extra docs build_docs.py | |
| - name: Upload artifacts | |
| if: steps.dv.outputs.metadata_only != 'true' | |
| uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 | |
| with: | |
| name: html-docs | |
| path: docs/_build/html/ | |
| retention-days: ${{ github.repository == 'NVIDIA/warp' && 7 || 1 }} | |
| - name: Deploy to gh-pages | |
| run: | | |
| flag="" | |
| if [[ "${{ steps.dv.outputs.metadata_only }}" == "true" ]]; then | |
| flag="--metadata-only" | |
| fi | |
| # Metadata-only tag deploys skip build_lib.py, so avoid syncing the | |
| # Warp project before running this stdlib-only script. | |
| uv run --no-project tools/ci/deploy_doc.py --version "${{ steps.dv.outputs.version }}" $flag | |
| git push origin gh-pages |