.github/workflows/docs.yml

   1 # LLVM Documentation CI
   2 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   3 # See https://llvm.org/LICENSE.txt for license information.
   4 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   5
   6 name: "Test documentation build"
   7
   8 permissions:
   9   contents: read
  10
  11 on:
  12   push:
  13     branches:
  14       - 'main'
  15     paths:
  16       - 'llvm/docs/**'
  17       - 'clang/docs/**'
  18       - 'clang/include/clang/Basic/AttrDocs.td'
  19       - 'clang/include/clang/Driver/ClangOptionDocs.td'
  20       - 'clang/include/clang/Basic/DiagnosticDocs.td'
  21       - 'clang-tools-extra/docs/**'
  22       - 'lldb/docs/**'
  23       - 'libunwind/docs/**'
  24       - 'libcxx/docs/**'
  25       - 'libc/docs/**'
  26       - 'lld/docs/**'
  27       - 'openmp/docs/**'
  28       - 'polly/docs/**'
  29       - 'flang/docs/**'
  30       - 'flang/include/flang/Optimizer/Dialect/FIROps.td'
  31       - '.github/workflows/docs.yml'
  32   pull_request:
  33     paths:
  34       - 'llvm/docs/**'
  35       - 'clang/docs/**'
  36       - 'clang/include/clang/Basic/AttrDocs.td'
  37       - 'clang/include/clang/Driver/ClangOptionDocs.td'
  38       - 'clang/include/clang/Basic/DiagnosticDocs.td'
  39       - 'clang-tools-extra/docs/**'
  40       - 'lldb/docs/**'
  41       - 'libunwind/docs/**'
  42       - 'libcxx/docs/**'
  43       - 'libc/docs/**'
  44       - 'lld/docs/**'
  45       - 'openmp/docs/**'
  46       - 'polly/docs/**'
  47       - 'flang/docs/**'
  48       - 'flang/include/flang/Optimizer/Dialect/FIROps.td'
  49       - '.github/workflows/docs.yml'
  50
  51 jobs:
  52   check-docs-build:
  53     name: "Test documentation build"
  54     runs-on: ubuntu-latest
  55     if: github.repository == 'llvm/llvm-project'
  56     steps:
  57       # Don't fetch before checking for file changes to force the file changes
  58       # action to use the Github API in pull requests. If it's a push to a
  59       # branch we can't use the Github API to get the diff, so we need to have
  60       # a local checkout beforehand.
  61       - name: Fetch LLVM sources (Push)
  62         if: ${{ github.event_name == 'push' }}
  63         uses: actions/checkout@v4
  64         with:
  65           fetch-depth: 1
  66       - name: Get subprojects that have doc changes
  67         id: docs-changed-subprojects
  68         uses: tj-actions/changed-files@v39
  69         with:
  70           files_yaml: |
  71             llvm:
  72               - 'llvm/docs/**'
  73             clang:
  74               - 'clang/docs/**'
  75               - 'clang/include/clang/Basic/AttrDocs.td'
  76               - 'clang/include/clang/Driver/ClangOptionDocs.td'
  77               - 'clang/include/clang/Basic/DiagnosticDocs.td'
  78             clang-tools-extra:
  79               - 'clang-tools-extra/docs/**'
  80             lldb:
  81               - 'lldb/docs/**'
  82             libunwind:
  83               - 'libunwind/docs/**'
  84             libcxx:
  85               - 'libcxx/docs/**'
  86             libc:
  87               - 'libc/docs/**'
  88             lld:
  89               - 'lld/docs/**'
  90             openmp:
  91               - 'openmp/docs/**'
  92             polly:
  93               - 'polly/docs/**'
  94             flang:
  95               - 'flang/docs/**'
  96               - 'flang/include/flang/Optimizer/Dialect/FIROps.td'
  97             workflow:
  98               - '.github/workflows/docs.yml'
  99       - name: Fetch LLVM sources (PR)
 100         if: ${{ github.event_name == 'pull_request' }}
 101         uses: actions/checkout@v4
 102         with:
 103           fetch-depth: 1
 104       - name: Setup Python env
 105         uses: actions/setup-python@v5
 106         with:
 107           python-version: '3.11'
 108           cache: 'pip'
 109           cache-dependency-path: 'llvm/docs/requirements-hashed.txt'
 110       - name: Install python dependencies
 111         run: pip install -r llvm/docs/requirements-hashed.txt
 112       - name: Install system dependencies
 113         run: |
 114           sudo apt-get update
 115           # swig and graphviz are lldb specific dependencies
 116           sudo apt-get install -y cmake ninja-build swig graphviz
 117       - name: Setup output folder
 118         run: mkdir built-docs
 119       - name: Build LLVM docs
 120         if: |
 121           steps.docs-changed-subprojects.outputs.llvm_any_changed == 'true' ||
 122           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 123         run: |
 124           cmake -B llvm-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX=ON ./llvm
 125           TZ=UTC ninja -C llvm-build docs-llvm-html docs-llvm-man
 126           mkdir built-docs/llvm
 127           cp -r llvm-build/docs/* built-docs/llvm/
 128       - name: Build Clang docs
 129         if: |
 130           steps.docs-changed-subprojects.outputs.clang_any_changed == 'true' ||
 131           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 132         run: |
 133           cmake -B clang-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_SPHINX=ON ./llvm
 134           TZ=UTC ninja -C clang-build docs-clang-html docs-clang-man
 135           mkdir built-docs/clang
 136           cp -r clang-build/docs/* built-docs/clang/
 137       - name: Build clang-tools-extra docs
 138         if: |
 139           steps.docs-changed-subprojects.outputs.clang-tools-extra_any_changed == 'true' ||
 140           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 141         run: |
 142           cmake -B clang-tools-extra-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -DLLVM_ENABLE_SPHINX=ON ./llvm
 143           TZ=UTC ninja -C clang-tools-extra-build docs-clang-tools-html docs-clang-tools-man
 144           mkdir built-docs/clang-tools-extra
 145           cp -r clang-tools-extra-build/docs/* built-docs/clang-tools-extra/
 146       - name: Build LLDB docs
 147         if: |
 148           steps.docs-changed-subprojects.outputs.lldb_any_changed == 'true' ||
 149           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 150         run: |
 151           cmake -B lldb-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;lldb" -DLLVM_ENABLE_SPHINX=ON ./llvm
 152           TZ=UTC ninja -C lldb-build docs-lldb-html docs-lldb-man
 153           mkdir built-docs/lldb
 154           cp -r lldb-build/docs/* built-docs/lldb/
 155       - name: Build libunwind docs
 156         if: |
 157           steps.docs-changed-subprojects.outputs.libunwind_any_changed == 'true' ||
 158           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 159         run: |
 160           cmake -B libunwind-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="libunwind" -DLLVM_ENABLE_SPHINX=ON ./runtimes
 161           TZ=UTC ninja -C libunwind-build docs-libunwind-html
 162           mkdir built-docs/libunwind
 163           cp -r libunwind-build/libunwind/docs/* built-docs/libunwind
 164       - name: Build libcxx docs
 165         if: |
 166           steps.docs-changed-subprojects.outputs.libcxx_any_changed == 'true' ||
 167           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 168         run: |
 169           cmake -B libcxx-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="libcxxabi;libcxx;libunwind" -DLLVM_ENABLE_SPHINX=ON ./runtimes
 170           TZ=UTC ninja -C libcxx-build docs-libcxx-html
 171           mkdir built-docs/libcxx
 172           cp -r libcxx-build/libcxx/docs/* built-docs/libcxx/
 173       - name: Build libc docs
 174         if: |
 175           steps.docs-changed-subprojects.outputs.libc_any_changed == 'true' ||
 176           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 177         run: |
 178           cmake -B libc-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="libc" -DLLVM_ENABLE_SPHINX=ON ./runtimes
 179           TZ=UTC ninja -C libc-build docs-libc-html
 180           mkdir built-docs/libc
 181           cp -r libc-build/libc/docs/* built-docs/libc/
 182       - name: Build LLD docs
 183         if: |
 184           steps.docs-changed-subprojects.outputs.lld_any_changed == 'true' ||
 185           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 186         run: |
 187           cmake -B lld-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="lld" -DLLVM_ENABLE_SPHINX=ON ./llvm
 188           TZ=UTC ninja -C lld-build docs-lld-html
 189           mkdir built-docs/lld
 190           cp -r lld-build/docs/* built-docs/lld/
 191       - name: Build OpenMP docs
 192         if: |
 193           steps.docs-changed-subprojects.outputs.openmp_any_changed == 'true' ||
 194           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 195         run: |
 196           cmake -B openmp-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;openmp" -DLLVM_ENABLE_SPHINX=ON ./llvm
 197           TZ=UTC ninja -C openmp-build docs-openmp-html
 198           mkdir built-docs/openmp
 199           cp -r openmp-build/docs/* built-docs/openmp/
 200       - name: Build Polly docs
 201         if: |
 202           steps.docs-changed-subprojects.outputs.polly_any_changed == 'true' ||
 203           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 204         run: |
 205           cmake -B polly-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="polly" -DLLVM_ENABLE_SPHINX=ON ./llvm
 206           TZ=UTC ninja -C polly-build docs-polly-html docs-polly-man
 207           mkdir built-docs/polly
 208           cp -r polly-build/docs/* built-docs/polly/
 209       - name: Build Flang docs
 210         if: |
 211           steps.docs-changed-subprojects.outputs.flang_any_changed == 'true' ||
 212           steps.docs-changed-subprojects.outputs.workflow_any_changed == 'true'
 213         run: |
 214           cmake -B flang-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" -DLLVM_ENABLE_SPHINX=ON ./llvm
 215           TZ=UTC ninja -C flang-build docs-flang-html
 216           mkdir built-docs/flang
 217           cp -r flang-build/docs/* built-docs/flang/
 218       - name: Upload docs
 219         uses: actions/upload-artifact@v4
 220         with:
 221           name: docs-output
 222           path: built-docs/