Repository navigation
Add AIF 0.1.0 (Preview) #21
Workflow file for this run
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
| name: Build and Deploy Docs | |
| on: | |
| push: | |
| branches: | |
| - main | |
| - release_* | |
| - preview_* | |
| tags: ["v*"] | |
| workflow_dispatch: | |
| inputs: | |
| version_tag: | |
| description: "Git tag to build docs from (e.g. v0.2.0). Leave blank to build from HEAD." | |
| required: false | |
| type: string | |
| branch_ref: | |
| description: "Branch to build docs from (e.g. release_2026-04-1 or preview_my-feature)." | |
| required: false | |
| type: string | |
| permissions: | |
| contents: write | |
| pages: read | |
| jobs: | |
| build-and-deploy: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout source | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: ${{ inputs.branch_ref || inputs.version_tag || github.ref }} | |
| fetch-depth: 0 | |
| submodules: recursive | |
| lfs: true | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.12" | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r requirements-docs.txt | |
| - name: Ensure docs version helper | |
| run: | | |
| if [[ ! -f scripts/docs_version_refs.py ]]; then | |
| mkdir -p scripts | |
| git show origin/main:scripts/docs_version_refs.py > scripts/docs_version_refs.py | |
| fi | |
| - name: Fetch release and preview branches | |
| run: python scripts/docs_version_refs.py fetch | |
| - name: Determine version | |
| id: version | |
| run: | | |
| TAG_INPUT="${{ inputs.version_tag }}" | |
| BRANCH_INPUT="${{ inputs.branch_ref }}" | |
| SOURCE_REF="${{ github.ref }}" | |
| if [[ -n "$BRANCH_INPUT" ]]; then | |
| SOURCE_REF="refs/heads/$BRANCH_INPUT" | |
| elif [[ -n "$TAG_INPUT" ]]; then | |
| SOURCE_REF="refs/tags/$TAG_INPUT" | |
| fi | |
| VER="$(python scripts/docs_version_refs.py version "$SOURCE_REF")" | |
| LABEL="$(python scripts/docs_version_refs.py label "$VER")" | |
| echo "ver=$VER" >> "$GITHUB_OUTPUT" | |
| echo "label=$LABEL" >> "$GITHUB_OUTPUT" | |
| echo "source_ref=$SOURCE_REF" >> "$GITHUB_OUTPUT" | |
| # Only update /latest/ on pushes to main (not tag, branch, or manual builds) | |
| if [[ "$SOURCE_REF" == refs/heads/main && -z "$TAG_INPUT" && -z "$BRANCH_INPUT" ]]; then | |
| echo "update_latest=true" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "update_latest=false" >> "$GITHUB_OUTPUT" | |
| fi | |
| echo "Building docs version: $VER from $SOURCE_REF" | |
| - name: Get Pages URL | |
| id: pages | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| PAGES_URL=$(gh api "repos/${{ github.repository }}/pages" --jq '.html_url' 2>/dev/null || echo "") | |
| PAGES_URL="${PAGES_URL%/}" | |
| if [[ -z "$PAGES_URL" ]]; then | |
| echo "::warning::Could not fetch Pages URL; falling back to convention" | |
| PAGES_URL="https://${{ github.repository_owner }}.github.io/$(echo '${{ github.repository }}' | cut -d/ -f2)" | |
| fi | |
| echo "url=$PAGES_URL" >> "$GITHUB_OUTPUT" | |
| echo "Pages URL: $PAGES_URL" | |
| - name: Build docs | |
| env: | |
| DOCS_VERSION: ${{ steps.version.outputs.ver }} | |
| DOCS_VERSION_LABEL: ${{ steps.version.outputs.label }} | |
| DOCS_BASE_URL: "${{ steps.pages.outputs.url }}/${{ steps.version.outputs.ver }}/" | |
| DOCS_VERSIONS_JSON: "${{ steps.pages.outputs.url }}/versions.json" | |
| run: python build_docs.py | |
| - name: Deploy versioned docs to gh-pages | |
| env: | |
| VERSION: ${{ steps.version.outputs.ver }} | |
| SOURCE_REF: ${{ steps.version.outputs.source_ref }} | |
| UPDATE_LATEST: ${{ steps.version.outputs.update_latest }} | |
| PAGES_URL: ${{ steps.pages.outputs.url }} | |
| run: | | |
| DOCS_BUILD="nv_core/sr_specs/docs/_build/html" | |
| DEPLOY_DIR=$(mktemp -d) | |
| # Clone existing gh-pages content (or start fresh) | |
| git clone --branch gh-pages --single-branch --depth 1 \ | |
| "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" \ | |
| "$DEPLOY_DIR" 2>/dev/null || { | |
| mkdir -p "$DEPLOY_DIR" | |
| cd "$DEPLOY_DIR" | |
| git init -b gh-pages | |
| } | |
| cd "$DEPLOY_DIR" | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| touch .nojekyll | |
| # Remove stale root-level Sphinx artifacts from pre-versioning deploys | |
| rm -f *.html *.js *.inv .buildinfo | |
| rm -rf _static _sources _images _downloads _sphinx_design_static \ | |
| _doctrees capabilities features guides indexes profiles | |
| # Drop preview branch folders superseded by mapped slug dirs | |
| while IFS= read -r stale; do | |
| [[ -n "$stale" ]] && rm -rf "$stale" | |
| done < <(python "$GITHUB_WORKSPACE/scripts/docs_version_refs.py" stale-dirs "$SOURCE_REF") | |
| while IFS= read -r stale; do | |
| [[ -n "$stale" ]] && rm -rf "$stale" | |
| done < <(python "$GITHUB_WORKSPACE/scripts/docs_version_refs.py" cleanup-previews "$DEPLOY_DIR") | |
| # Place build into versioned subdirectory | |
| rm -rf "$VERSION" | |
| cp -r "$GITHUB_WORKSPACE/$DOCS_BUILD" "$VERSION" | |
| # Update /latest/ on pushes to main | |
| if [[ "$UPDATE_LATEST" == "true" ]]; then | |
| rm -rf latest | |
| cp -r "$VERSION" latest | |
| fi | |
| # Generate versions.json for the in-docs version switcher dropdown | |
| echo '[' > versions.json | |
| first=true | |
| for d in $(ls -d */ 2>/dev/null | grep -v '^latest/$' | sort -rV); do | |
| v="${d%/}" | |
| label="$(python "$GITHUB_WORKSPACE/scripts/docs_version_refs.py" label "$v")" | |
| if [[ "$first" == "true" && "$label" == "$v" ]]; then | |
| label="$v (latest)" | |
| first=false | |
| fi | |
| echo ' {"name": "'"$label"'", "version": "'"$v"'", "url": "'"$PAGES_URL"'/'"$v"'/"},' >> versions.json | |
| done | |
| # Remove trailing comma and close array | |
| sed -i '$ s/,$//' versions.json | |
| echo ']' >> versions.json | |
| # Generate root index.html version picker | |
| { | |
| echo '<!DOCTYPE html>' | |
| echo '<html lang="en"><head><meta charset="utf-8">' | |
| echo '<title>SimReady Foundation Docs</title>' | |
| echo '<style>' | |
| echo ' body { font-family: system-ui, sans-serif; max-width: 600px;' | |
| echo ' margin: 4rem auto; padding: 0 1rem; }' | |
| echo ' h1 { font-size: 1.4rem; }' | |
| echo ' ul { list-style: none; padding: 0; }' | |
| echo ' li { margin: 0.5rem 0; }' | |
| echo ' a { color: #76b900; text-decoration: none; font-weight: 600; }' | |
| echo ' a:hover { text-decoration: underline; }' | |
| echo '</style></head><body>' | |
| echo '<h1>SimReady Foundation Documentation</h1>' | |
| echo '<ul>' | |
| echo ' <li><a href="latest/">latest</a></li>' | |
| for d in $(ls -d */ 2>/dev/null | grep -v '^latest/$' | sort -rV); do | |
| v="${d%/}" | |
| label="$(python "$GITHUB_WORKSPACE/scripts/docs_version_refs.py" label "$v")" | |
| echo " <li><a href=\"$v/\">$label</a></li>" | |
| done | |
| echo '</ul></body></html>' | |
| } > index.html | |
| git add -A | |
| git diff --cached --quiet && echo "No changes to deploy" && exit 0 | |
| git commit -m "Deploy docs $VERSION from ${GITHUB_SHA::8}" | |
| git push --force "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" gh-pages |