doc-build.yml

# Copyright (c) 2021-2024 TiaC Systems
# Copyright (c) 2021 Li-Pro.Net
# SPDX-License-Identifier: Apache-2.0

name: Documentation Build

on:
  workflow_dispatch: # And manually on button click
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main
      - 'v*-branch'
    paths:
      - 'VERSION'
      - 'doc/**'
      - '**.rst'
      - 'include/**'
      - '.known-issues/doc/**'
      - '**/Kconfig*'
      - 'scripts/tools-versions-*'
      - 'scripts/requirements-*'
      - 'scripts/requirements.txt'
      - 'west.yml'
      - '.github/workflows/doc-*.yml'
  push:
    tags:
      - 'v*'
    branches:
      - main
      - 'v*-branch'
    paths:
      - 'VERSION'
      - 'doc/**'
      - '**.rst'
      - 'include/**'
      - '.known-issues/doc/**'
      - '**/Kconfig*'
      - 'scripts/tools-versions-*'
      - 'scripts/requirements-*'
      - 'scripts/requirements.txt'
      - 'west.yml'
      - '.github/workflows/doc-*.yml'

jobs:
  doc-build:
    name: Build and upload documentation to artifacts
    runs-on: ubuntu-latest

    steps:
      - name: Apply container HTTP/2 framing layer workaround
        run: |
          # FIXME: For unknown reasons, the local development host and CI is
          #        running in temporary "Error in the HTTP2 framing layer".
          #        Forcing the historical but still supported HTTP/1.1 layer
          #        seems to be a stable workaround - happened in Oct. 2023.
          git config --global --add http.version HTTP/1.1

      - name: Update GitHub PATH for west
        run: |
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Checkout the code
        uses: actions/checkout@v4
        with:
          path: workspace/bridle

      - name: Install packages
        run: |
          sudo add-apt-repository -y -u ppa:tiac-systems/doxygen
          sudo apt-get install -y ninja-build doxygen mscgen graphviz

      - name: Restore PIP Cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-doc-pip

      - name: Install base dependencies
        working-directory: workspace
        run: |
          pip3 install --upgrade pip
          pip3 install --upgrade setuptools
          pip3 install --upgrade --requirement bridle/scripts/requirements-base.txt

      - name: West init and update
        working-directory: workspace
        run: |
          west init --local bridle
          west update --fetch=always --stats
          west zephyr-export
          west bridle-export

      - name: Install documentation dependencies
        working-directory: workspace
        run: |
          pip3 install --upgrade --requirement zephyr/scripts/requirements-base.txt
          pip3 install --upgrade --requirement zephyr/scripts/requirements-build-test.txt
          pip3 install --upgrade --requirement bridle/scripts/requirements-doc.txt

      - name: Build documentation
        working-directory: workspace
        run: |
          cmake -B build -GNinja bridle/doc
          ninja -C build build-all
          #
          # For some unknown reason, the layout of the Sphinx Tabs extension
          # in the docset "devicetree" is no longer rendered properly by the
          # HTML Builder of Sphinx v6. Only cleaning it up and rebuilding it
          # helps so far.
          #
          ninja -C build devicetree-clean
          ninja -C build devicetree-html

      - name: Archive documentation
        working-directory: workspace/build
        run: |
          # synopsys: publish2 <catalog> <version> <archive>
          #   <catalog> := {development|approved}
          #   <version> := {latest|<branch>}
          #   <archive> := doc_build_<GITHUB_RUN_ID_from_doc-build>.tgz
          mkdir doc && cd doc
          archive="doc_build_${GITHUB_RUN_ID}.tgz"
          tar -C ../html -zcf ${archive} .
          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            # basename will work for both branches and tags
            branch=$(basename "${{ github.ref }}")
            echo "publish2 preview REF-${branch} ${archive}" > "monitor_${GITHUB_RUN_ID}.txt"
          else
            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
              echo "publish2 development PR-${{ github.event.number }} ${archive}" > \
                   "monitor_${GITHUB_RUN_ID}.txt"
              echo "${{ github.event.number }}" > pr.txt
            else
              # basename will work for both branches and tags
              branch=$(basename "${{ github.ref }}")
              if [[ "${branch}" == "main" ]]; then
                echo "publish2 approved latest ${archive}" > "monitor_${GITHUB_RUN_ID}.txt"
              else
                echo "publish2 approved ${branch} ${archive}" > "monitor_${GITHUB_RUN_ID}.txt"
              fi
            fi
          fi

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: doc
          path: workspace/build/doc