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:
        # 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