zephyr/.github/workflows/doc-build.yml

# Copyright (c) 2020 Linaro Limited.
# SPDX-License-Identifier: Apache-2.0

name: Documentation Build

on:
  schedule:
  - cron: '0 */3 * * *'
  push:
    tags:
    - v*
  pull_request:
    paths:
    - 'doc/**'
    - '**.rst'
    - 'include/**'
    - 'kernel/include/kernel_arch_interface.h'
    - 'lib/libc/**'
    - 'subsys/testsuite/ztest/include/**'
    - 'tests/**'
    - '**/Kconfig*'
    - 'west.yml'
    - '.github/workflows/doc-build.yml'
    - 'scripts/dts/**'
    - 'scripts/requirements-doc.txt'

env:
  # NOTE: west docstrings will be extracted from the version listed here
  WEST_VERSION: 1.0.0
  # The latest CMake available directly with apt is 3.18, but we need >=3.20
  # so we fetch that through pip.
  CMAKE_VERSION: 3.20.5
  DOXYGEN_VERSION: 1.9.6

jobs:
  doc-build-html:
    name: "Documentation Build (HTML)"
    runs-on: ubuntu-22.04
    timeout-minutes: 45
    concurrency:
      group: doc-build-html-${{ github.ref }}
      cancel-in-progress: true

    steps:
    - name: checkout
      uses: actions/checkout@v3

    - name: install-pkgs
      run: |
        sudo apt-get update
        sudo apt-get install -y ninja-build graphviz
        wget --no-verbose "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
        tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz
        echo "${PWD}/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH        

    - name: cache-pip
      uses: actions/cache@v3
      with:
        path: ~/.cache/pip
        key: pip-${{ hashFiles('scripts/requirements-doc.txt') }}

    - name: install-pip
      run: |
        sudo pip3 install -U setuptools wheel pip
        pip3 install -r scripts/requirements-doc.txt
        pip3 install west==${WEST_VERSION}
        pip3 install cmake==${CMAKE_VERSION}        

    - name: west setup
      run: |
        west init -l .        

    - name: build-docs
      shell: bash
      run: |
        if [[ "$GITHUB_REF" =~ "refs/tags/v" ]]; then
          DOC_TAG="release"
        else
          DOC_TAG="development"
        fi

        if [[ "${{ github.event_name }}" == "pull_request" ]]; then
          DOC_TARGET="html-fast"
        else
          DOC_TARGET="html"
        fi

        DOC_TAG=${DOC_TAG} SPHINXOPTS="-q -W --keep-going -t publish" make -C doc ${DOC_TARGET}        

    - name: compress-docs
      run: |
        tar cfJ html-output.tar.xz --directory=doc/_build html        

    - name: upload-build
      uses: actions/upload-artifact@v3
      with:
        name: html-output
        path: html-output.tar.xz

    - name: process-pr
      if: github.event_name == 'pull_request'
      run: |
        REPO_NAME="${{ github.event.repository.name }}"
        PR_NUM="${{ github.event.pull_request.number }}"
        DOC_URL="https://builds.zephyrproject.io/${REPO_NAME}/pr/${PR_NUM}/docs/"

        echo "${PR_NUM}" > pr_num
        echo "Documentation will be available shortly at: ${DOC_URL}" >> $GITHUB_STEP_SUMMARY        

    - name: upload-pr-number
      uses: actions/upload-artifact@v3
      if: github.event_name == 'pull_request'
      with:
        name: pr_num
        path: pr_num

  doc-build-pdf:
    name: "Documentation Build (PDF)"
    if: github.event_name != 'pull_request'
    runs-on: zephyr-runner-linux-x64-4xlarge
    container: texlive/texlive:latest
    timeout-minutes: 60
    concurrency:
      group: doc-build-pdf-${{ github.ref }}
      cancel-in-progress: true

    steps:
    - name: checkout
      uses: actions/checkout@v3

    - name: install-pkgs
      run: |
        apt-get update
        apt-get install -y python3-pip python3-venv ninja-build doxygen graphviz librsvg2-bin        

    - name: cache-pip
      uses: actions/cache@v3
      with:
        path: ~/.cache/pip
        key: pip-${{ hashFiles('scripts/requirements-doc.txt') }}

    - name: setup-venv
      run: |
        python3 -m venv .venv
        . .venv/bin/activate
        echo PATH=$PATH >> $GITHUB_ENV        

    - name: install-pip
      run: |
        pip3 install -U setuptools wheel pip
        pip3 install -r scripts/requirements-doc.txt
        pip3 install west==${WEST_VERSION}
        pip3 install cmake==${CMAKE_VERSION}        

    - name: west setup
      run: |
        west init -l .        

    - name: build-docs
      shell: bash
      continue-on-error: true
      run: |
        if [[ "$GITHUB_REF" =~ "refs/tags/v" ]]; then
          DOC_TAG="release"
        else
          DOC_TAG="development"
        fi

        DOC_TAG=${DOC_TAG} SPHINXOPTS="-q -j auto" LATEXMKOPTS="-quiet -halt-on-error" make -C doc pdf        

    - name: upload-build
      if: always()
      uses: actions/upload-artifact@v3
      with:
        name: pdf-output
        if-no-files-found: ignore
        path: |
          doc/_build/latex/zephyr.pdf
          doc/_build/latex/zephyr.log