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:
  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:
        # Multi-version docs always use develop's Sphinx configuration,
        # including when manually dispatched from the release landing branch.
        ref: develop

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

    - name: Install docs dependencies
      run: |
        uv sync --extra dev
        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,
        # stable tags >= v2.0.0, and v3.0.0-beta2. Other release branches and
        # prerelease tags are excluded.
        SMV_BRANCH_WHITELIST: '^(main|develop|release/3\.0\.0)$'
        SMV_TAG_WHITELIST: '^v([2-9]\d*\.\d+\.\d+|3\.0\.0-beta2)$'
      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