.github/workflows/docs.yml

# LLVM Documentation CI
# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

name: "Test documentation build"

permissions:
  contents: read

on:
  push:
    branches:
      - 'main'
    paths:
      - 'bolt/docs/**'
      - 'llvm/docs/**'
      - 'clang/docs/**'
      - 'clang/include/clang/Basic/AttrDocs.td'
      - 'clang/include/clang/Driver/ClangOptionDocs.td'
      - 'clang/include/clang/Basic/DiagnosticDocs.td'
      - 'clang-tools-extra/docs/**'
      - 'lldb/docs/**'
      - 'libunwind/docs/**'
      - 'libcxx/docs/**'
      - 'libc/docs/**'
      - 'lld/docs/**'
      - 'openmp/docs/**'
      - 'polly/docs/**'
      - 'flang/docs/**'
      - 'flang/include/flang/Optimizer/Dialect/FIROps.td'
      - '.github/workflows/docs.yml'
  pull_request:
    paths:
      - 'bolts/docs/**'
      - 'llvm/docs/**'
      - 'clang/docs/**'
      - 'clang/include/clang/Basic/AttrDocs.td'
      - 'clang/include/clang/Driver/ClangOptionDocs.td'
      - 'clang/include/clang/Basic/DiagnosticDocs.td'
      - 'clang-tools-extra/docs/**'
      - 'lldb/docs/**'
      - 'libunwind/docs/**'
      - 'libcxx/docs/**'
      - 'libc/docs/**'
      - 'lld/docs/**'
      - 'openmp/docs/**'
      - 'polly/docs/**'
      - 'flang/docs/**'
      - 'flang/include/flang/Optimizer/Dialect/FIROps.td'
      - '.github/workflows/docs.yml'
      - 'utils/docs/**'

jobs:
  check-docs-build:
    name: "Test documentation build"
    runs-on: ubuntu-26.04
    if: github.repository == 'llvm/llvm-project'
    steps:
      - name: Fetch LLVM sources
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 2
      - name: Get subprojects that have doc changes
        id: docs-changed-subprojects
        uses: tj-actions/changed-files@9426d40962ed5378910ee2e21d5f8c6fcbf2dd96 # v47.0.6
        with:
          skip_initial_fetch: true
          base_sha: 'HEAD~1'
          sha: 'HEAD'
          files_yaml: |
            llvm:
              - 'llvm/docs/**'
            bolt:
              - 'bolt/docs/**'
            clang:
              - 'clang/docs/**'
              - 'clang/include/clang/Basic/AttrDocs.td'
              - 'clang/include/clang/Driver/ClangOptionDocs.td'
              - 'clang/include/clang/Basic/DiagnosticDocs.td'
            clang-tools-extra:
              - 'clang-tools-extra/docs/**'
            lldb:
              - 'lldb/docs/**'
            libunwind:
              - 'libunwind/docs/**'
            libcxx:
              - 'libcxx/docs/**'
            libc:
              - 'libc/docs/**'
            lld:
              - 'lld/docs/**'
            openmp:
              - 'openmp/docs/**'
            polly:
              - 'polly/docs/**'
            flang:
              - 'flang/docs/**'
              - 'flang/include/flang/Optimizer/Dialect/FIROps.td'
            common:
              - '.github/workflows/docs.yml'
              - 'utils/docs/**'
      - name: Setup Python env
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.14'
          cache: 'pip'
          cache-dependency-path: 'llvm/docs/requirements.txt'
      - name: Install python dependencies
        run: pip install --require-hashes -r llvm/docs/requirements.txt
      - name: Install system dependencies
        run: |
          sudo apt-get update
          # swig and graphviz are lldb specific dependencies
          sudo apt-get install -y cmake ninja-build swig graphviz
      - name: Setup output folder
        run: mkdir built-docs
      - name: Build LLVM docs
        if: |
          steps.docs-changed-subprojects.outputs.llvm_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B llvm-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C llvm-build docs-llvm-html docs-llvm-man
          mkdir built-docs/llvm
          cp -r llvm-build/docs/* built-docs/llvm/
      - name: Build BOLT docs
        if: |
          steps.docs-changed-subprojects.outputs.bolt_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B bolt-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="bolt" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C bolt-build docs-bolt-html
          mkdir built-docs/bolt
          cp -r bolt-build/docs/* built-docs/bolt/
      - name: Build Clang docs
        if: |
          steps.docs-changed-subprojects.outputs.clang_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B clang-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C clang-build docs-clang-html docs-clang-man
          mkdir built-docs/clang
          cp -r clang-build/docs/* built-docs/clang/
      - name: Build clang-tools-extra docs
        if: |
          steps.docs-changed-subprojects.outputs.clang-tools-extra_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B clang-tools-extra-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C clang-tools-extra-build docs-clang-tools-html docs-clang-tools-man
          mkdir built-docs/clang-tools-extra
          cp -r clang-tools-extra-build/docs/* built-docs/clang-tools-extra/
      - name: Build LLDB docs
        if: |
          steps.docs-changed-subprojects.outputs.lldb_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B lldb-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;lldb" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C lldb-build docs-lldb-html docs-lldb-man
          mkdir built-docs/lldb
          cp -r lldb-build/docs/* built-docs/lldb/
      - name: Build libunwind docs
        if: |
          steps.docs-changed-subprojects.outputs.libunwind_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B libunwind-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="libunwind" -DLLVM_ENABLE_SPHINX=ON ./runtimes
          TZ=UTC ninja -C libunwind-build docs-libunwind-html
          mkdir built-docs/libunwind
          cp -r libunwind-build/libunwind/docs/* built-docs/libunwind
      - name: Build libcxx docs
        if: |
          steps.docs-changed-subprojects.outputs.libcxx_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B libcxx-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="libcxxabi;libcxx;libunwind" -DLLVM_ENABLE_SPHINX=ON ./runtimes
          TZ=UTC ninja -C libcxx-build docs-libcxx-html
          mkdir built-docs/libcxx
          cp -r libcxx-build/libcxx/docs/* built-docs/libcxx/
      - name: Build libc docs
        if: |
          steps.docs-changed-subprojects.outputs.libc_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B libc-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="libc" -DLLVM_ENABLE_SPHINX=ON ./runtimes
          TZ=UTC ninja -C libc-build docs-libc-html
          mkdir built-docs/libc
          cp -r libc-build/libc/docs/* built-docs/libc/
      - name: Build LLD docs
        if: |
          steps.docs-changed-subprojects.outputs.lld_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B lld-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="lld" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C lld-build docs-lld-html
          mkdir built-docs/lld
          cp -r lld-build/docs/* built-docs/lld/
      - name: Build OpenMP docs
        if: |
          steps.docs-changed-subprojects.outputs.openmp_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B openmp-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_RUNTIMES="openmp" -DLLVM_ENABLE_SPHINX=ON -DLLVM_INCLUDE_TESTS=OFF ./runtimes
          TZ=UTC ninja -C openmp-build docs-openmp-html
          mkdir built-docs/openmp
          cp -r openmp-build/openmp/docs/* built-docs/openmp/
      - name: Build Polly docs
        if: |
          steps.docs-changed-subprojects.outputs.polly_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B polly-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="polly" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C polly-build docs-polly-html docs-polly-man
          mkdir built-docs/polly
          cp -r polly-build/docs/* built-docs/polly/
      - name: Build Flang docs
        if: |
          steps.docs-changed-subprojects.outputs.flang_any_changed == 'true' ||
          steps.docs-changed-subprojects.outputs.common_any_changed == 'true'
        run: |
          cmake -B flang-build -GNinja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" -DLLVM_ENABLE_SPHINX=ON ./llvm
          TZ=UTC ninja -C flang-build docs-flang-html docs-flang-man
          mkdir built-docs/flang
          cp -r flang-build/docs/* built-docs/flang/
      - name: Upload docs
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: docs-output
          path: built-docs/