1# Copyright (c) 2020 Linaro Limited.
2# SPDX-License-Identifier: Apache-2.0
3
4name: Documentation Build
5
6on:
7  schedule:
8  - cron: '0 */3 * * *'
9  push:
10    tags:
11    - v*
12  pull_request:
13    paths:
14    - 'doc/**'
15    - '**.rst'
16    - 'include/**'
17    - 'kernel/include/kernel_arch_interface.h'
18    - 'lib/libc/**'
19    - 'subsys/testsuite/ztest/include/**'
20    - 'tests/**'
21    - '**/Kconfig*'
22    - 'west.yml'
23    - '.github/workflows/doc-build.yml'
24    - 'scripts/dts/**'
25    - 'doc/requirements.txt'
26
27env:
28  # NOTE: west docstrings will be extracted from the version listed here
29  WEST_VERSION: 1.0.0
30  # The latest CMake available directly with apt is 3.18, but we need >=3.20
31  # so we fetch that through pip.
32  CMAKE_VERSION: 3.20.5
33  DOXYGEN_VERSION: 1.9.6
34
35jobs:
36  doc-build-html:
37    name: "Documentation Build (HTML)"
38    runs-on: zephyr-runner-linux-x64-4xlarge
39    timeout-minutes: 45
40    concurrency:
41      group: doc-build-html-${{ github.ref }}
42      cancel-in-progress: true
43
44    steps:
45    - name: checkout
46      uses: actions/checkout@v3
47      with:
48        ref: ${{ github.event.pull_request.head.sha }}
49        fetch-depth: 0
50
51    - name: Rebase
52      continue-on-error: true
53      env:
54        BASE_REF: ${{ github.base_ref }}
55        PR_HEAD: ${{ github.event.pull_request.head.sha }}
56      run: |
57        git config --global user.email "actions@zephyrproject.org"
58        git config --global user.name "Github Actions"
59        git rebase origin/${BASE_REF}
60        git log --graph --oneline HEAD...${PR_HEAD}
61
62    - name: install-pkgs
63      run: |
64        sudo apt-get update
65        sudo apt-get install -y ninja-build graphviz
66        wget --no-verbose "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
67        tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz
68        echo "${PWD}/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH
69
70    - name: cache-pip
71      uses: actions/cache@v3
72      with:
73        path: ~/.cache/pip
74        key: pip-${{ hashFiles('doc/requirements.txt') }}
75
76    - name: install-pip
77      run: |
78        sudo pip3 install -U setuptools wheel pip
79        pip3 install -r doc/requirements.txt
80        pip3 install west==${WEST_VERSION}
81        pip3 install cmake==${CMAKE_VERSION}
82
83    - name: west setup
84      run: |
85        west init -l .
86
87    - name: build-docs
88      shell: bash
89      run: |
90        if [[ "$GITHUB_REF" =~ "refs/tags/v" ]]; then
91          DOC_TAG="release"
92        else
93          DOC_TAG="development"
94        fi
95
96        if [[ "${{ github.event_name }}" == "pull_request" ]]; then
97          DOC_TARGET="html-fast"
98        else
99          DOC_TARGET="html"
100        fi
101
102        DOC_TAG=${DOC_TAG} SPHINXOPTS_EXTRA="-q -t publish" make -C doc ${DOC_TARGET}
103
104    - name: compress-docs
105      run: |
106        tar cfJ html-output.tar.xz --directory=doc/_build html
107
108    - name: upload-build
109      uses: actions/upload-artifact@v3
110      with:
111        name: html-output
112        path: html-output.tar.xz
113
114    - name: process-pr
115      if: github.event_name == 'pull_request'
116      run: |
117        REPO_NAME="${{ github.event.repository.name }}"
118        PR_NUM="${{ github.event.pull_request.number }}"
119        DOC_URL="https://builds.zephyrproject.io/${REPO_NAME}/pr/${PR_NUM}/docs/"
120
121        echo "${PR_NUM}" > pr_num
122        echo "Documentation will be available shortly at: ${DOC_URL}" >> $GITHUB_STEP_SUMMARY
123
124    - name: upload-pr-number
125      uses: actions/upload-artifact@v3
126      if: github.event_name == 'pull_request'
127      with:
128        name: pr_num
129        path: pr_num
130
131  doc-build-pdf:
132    name: "Documentation Build (PDF)"
133    if: github.event_name != 'pull_request'
134    runs-on: zephyr-runner-linux-x64-4xlarge
135    container: texlive/texlive:latest
136    timeout-minutes: 60
137    concurrency:
138      group: doc-build-pdf-${{ github.ref }}
139      cancel-in-progress: true
140
141    steps:
142    - name: checkout
143      uses: actions/checkout@v3
144
145    - name: install-pkgs
146      run: |
147        apt-get update
148        apt-get install -y python3-pip python3-venv ninja-build doxygen graphviz librsvg2-bin
149
150    - name: cache-pip
151      uses: actions/cache@v3
152      with:
153        path: ~/.cache/pip
154        key: pip-${{ hashFiles('doc/requirements.txt') }}
155
156    - name: setup-venv
157      run: |
158        python3 -m venv .venv
159        . .venv/bin/activate
160        echo PATH=$PATH >> $GITHUB_ENV
161
162    - name: install-pip
163      run: |
164        pip3 install -U setuptools wheel pip
165        pip3 install -r doc/requirements.txt
166        pip3 install west==${WEST_VERSION}
167        pip3 install cmake==${CMAKE_VERSION}
168
169    - name: west setup
170      run: |
171        west init -l .
172
173    - name: build-docs
174      shell: bash
175      continue-on-error: true
176      run: |
177        if [[ "$GITHUB_REF" =~ "refs/tags/v" ]]; then
178          DOC_TAG="release"
179        else
180          DOC_TAG="development"
181        fi
182
183        DOC_TAG=${DOC_TAG} SPHINXOPTS="-q -j auto" LATEXMKOPTS="-quiet -halt-on-error" make -C doc pdf
184
185    - name: upload-build
186      if: always()
187      uses: actions/upload-artifact@v3
188      with:
189        name: pdf-output
190        if-no-files-found: ignore
191        path: |
192          doc/_build/latex/zephyr.pdf
193          doc/_build/latex/zephyr.log
194