IsaacLab/.github/workflows/docs.yaml at main · redfler/IsaacLab · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
# 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]

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 }}"
    - id: trigger-deploy
      env:
        REPO_NAME: ${{ secrets.REPO_NAME }}
      # develop, main, release/ trigger multi-version build, then deployment to gh-pages
      # all others - just the current docs without deployment
      if: "${{ github.repository == env.REPO_NAME && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/release/')) }}"
      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

    - 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, tags >= v2.0.0
        # (including pre-release suffixes like -beta or -rc1). v1.x tags and
        # release/ branches are excluded.
        SMV_BRANCH_WHITELIST: '^(main|develop)$'
        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: 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
        force_orphan: true