docs.yaml

# 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:
  # Pushes and PRs still build current-docs (build-latest-docs). The expensive
  # multi-version deploy is owned by the nightly cron on the repository default
  # branch; develop / release pushes no longer deploy here.
  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.event.pull_request.number || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

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 }}"
    - id: trigger-deploy
      env:
        REPO_NAME: ${{ secrets.REPO_NAME }}
      # Multi-version deploy is owned by the nightly cron on the repository
      # default branch. Develop / release / feature pushes and PRs build
      # current-docs only and never deploy here.
      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: Set up uv
      uses: astral-sh/setup-uv@v6
      with:
        python-version: "3.12"
        enable-cache: true

    - name: Install docs dependencies
      run: |
        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" uv sync --extra test
        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"

    - 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

    - name: Set up uv
      uses: astral-sh/setup-uv@v6
      with:
        python-version: "3.12"
        enable-cache: true

    - name: Install docs dependencies
      run: |
        bash "$GITHUB_WORKSPACE/.github/actions/_lib/with-python-package-retries.sh" uv sync --extra test
        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"

    - 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, and
        # tags >= v2.0.0 (including pre-release suffixes like -beta or -rc1).
        # v1.x tags and other release branches are excluded.
        SMV_BRANCH_WHITELIST: '^(main|develop|release/3\.0\.0)$'
        SMV_TAG_WHITELIST: '^v[2-9]\d*\.\d+\.\d+(-[A-Za-z0-9.]+)?$'
      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: Set default docs version
      working-directory: ./docs
      env:
        DOCS_DEFAULT_REF: v3.0.0-beta2
      run: |
        test -n "$DOCS_DEFAULT_REF"
        test -f "_build/$DOCS_DEFAULT_REF/index.html" || {
          echo "::error::Default docs ref '$DOCS_DEFAULT_REF' was not built"
          exit 1
        }
        sed "s|url=\./[^\"]*/index.html|url=./$DOCS_DEFAULT_REF/index.html|" \
          _redirect/index.html > _build/index.html

    - name: Upload GitHub Pages artifact
      uses: actions/upload-pages-artifact@v4
      with:
        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'

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
    - name: Deploy GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4