Documentation Build #8250
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # 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/**' | |
| - 'doc/requirements.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('doc/requirements.txt') }} | |
| - name: install-pip | |
| run: | | |
| sudo pip3 install -U setuptools wheel pip | |
| pip3 install -r doc/requirements.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_EXTRA="-q -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('doc/requirements.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 doc/requirements.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 |