Docs #4
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
| # Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). | |
| # All rights reserved. | |
| # | |
| # SPDX-License-Identifier: BSD-3-Clause | |
| name: Docs | |
| on: | |
| push: | |
| branches: | |
| - main | |
| - develop | |
| - 'release/**' | |
| - 'feature/isaacsim-6-0' | |
| pull_request: | |
| # we're skipping the branches and paths filter to allow docs to be built on any PR because heredoc is used | |
| # additionally, we have a check that determines what version of docs will be built | |
| types: [opened, synchronize, reopened] | |
| # Nightly multi-version rebuild + deploy from develop tip. Picks up every | |
| # develop commit accumulated since the previous nightly in a single run. | |
| schedule: | |
| - cron: '0 2 * * *' # 6pm PST / 7pm PDT | |
| workflow_dispatch: | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| doc-build-type: | |
| name: Detect Doc Build Type | |
| runs-on: ubuntu-latest | |
| outputs: | |
| trigger-deploy: ${{ steps.trigger-deploy.outputs.defined }} | |
| steps: | |
| - id: info | |
| run: echo "repo=github.repository=${{ github.repository }}, ref=github.ref=${{ github.ref }}, event=github.event_name=${{ github.event_name }}" | |
| - id: trigger-deploy | |
| env: | |
| REPO_NAME: ${{ secrets.REPO_NAME }} | |
| # Nightly schedule and workflow_dispatch trigger multi-version deploy. | |
| # All branch pushes (including main) build current-docs only; deploy waits for the cron above. | |
| if: "${{ github.repository == env.REPO_NAME && (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') }}" | |
| run: echo "defined=true" >> "$GITHUB_OUTPUT"; echo "Docs will be built multi-version and deployed" | |
| build-latest-docs: | |
| name: Build Latest Docs | |
| runs-on: ubuntu-latest | |
| needs: [doc-build-type] | |
| # run on non-deploy branches to build current version docs only | |
| if: needs.doc-build-type.outputs.trigger-deploy != 'true' | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v6 | |
| - name: Setup python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.12" | |
| architecture: x64 | |
| - name: Install dev requirements | |
| working-directory: ./docs | |
| run: pip install -r requirements.txt | |
| - name: Build current version docs | |
| working-directory: ./docs | |
| run: make current-docs | |
| - name: Upload docs artifact | |
| uses: actions/upload-artifact@v7 | |
| with: | |
| name: docs-html | |
| path: ./docs/_build | |
| build-multi-docs: | |
| name: Build Multi-Version Docs | |
| runs-on: ubuntu-latest | |
| needs: [doc-build-type] | |
| # run on deploy branches to create multi-version docs | |
| if: needs.doc-build-type.outputs.trigger-deploy == 'true' | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v6 | |
| with: | |
| # On schedule, always rebuild from the develop tip regardless of | |
| # which ref the cron run defaults to. Other events use github.ref. | |
| ref: ${{ github.event_name == 'schedule' && 'develop' || '' }} | |
| - name: Setup python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.12" | |
| architecture: x64 | |
| - name: Install dev requirements | |
| working-directory: ./docs | |
| run: pip install -r requirements.txt | |
| - name: Generate multi-version docs | |
| working-directory: ./docs | |
| env: | |
| # "deploy" branches build the full set of versions so every page | |
| # has a complete version dropdown: main, develop, release/3.0.0-beta2, | |
| # and stable tags >= v2.0.0. Other release branches and prerelease tags | |
| # are excluded. | |
| SMV_BRANCH_WHITELIST: '^(main|develop|release/3\.0\.0-beta2)$' | |
| SMV_TAG_WHITELIST: '^v[2-9]\d*\.\d+\.\d+$' | |
| run: | | |
| git fetch --prune --unshallow --tags | |
| git checkout --detach HEAD | |
| git for-each-ref --format="%(refname:short)" refs/heads/ | xargs -r git branch -D | |
| make multi-docs | |
| - name: Upload docs artifact | |
| uses: actions/upload-artifact@v7 | |
| with: | |
| name: docs-html | |
| path: ./docs/_build | |
| deploy-docs: | |
| name: Deploy Docs | |
| runs-on: ubuntu-latest | |
| needs: [doc-build-type, build-multi-docs] | |
| # deploy only on "deploy" branches | |
| if: needs.doc-build-type.outputs.trigger-deploy == 'true' | |
| steps: | |
| - name: Download docs artifact | |
| uses: actions/download-artifact@v8 | |
| with: | |
| name: docs-html | |
| path: ./docs/_build | |
| - name: Deploy to gh-pages | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/_build | |
| keep_files: false |