b4f968cf9d
Add a new toctree with reference material, including: - API docs (Doxygen) - Kconfig options - Devicetree bindings Note that the toctree is rendered manually due to the limitations Sphinx has when it comes to including relative URLs. Hardcoding absolute URLs in toctrees is possible, but that means we'd need to update the toctree on every release (to point to /version/ URL), and downstream users of the documentation would have to manually patch the toctree with their own URL. In order to make local builds work, version prefix is only added if publish tag is provided. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
134 lines
3.3 KiB
YAML
134 lines
3.3 KiB
YAML
# 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: 0.11.1
|
|
# 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.1
|
|
|
|
jobs:
|
|
doc-build-html:
|
|
name: "Documentation Build (HTML)"
|
|
runs-on: ubuntu-latest
|
|
|
|
steps:
|
|
- name: checkout
|
|
uses: actions/checkout@v2
|
|
|
|
- name: install-pkgs
|
|
run: |
|
|
sudo apt-get install -y ninja-build graphviz libclang1-9 libclang-cpp9
|
|
wget -q https://www.doxygen.nl/files/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@v1
|
|
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
|
|
run: |
|
|
if [[ "$GITHUB_REF" =~ "refs/tags/v" ]]; then
|
|
DOC_TAG="release"
|
|
else
|
|
DOC_TAG="development"
|
|
fi
|
|
|
|
DOC_TAG=${DOC_TAG} SPHINXOPTS="-q -W -j auto -t publish" make -C doc html
|
|
|
|
- name: compress-docs
|
|
run: |
|
|
tar cfJ html-output.tar.xz --directory=doc/_build html
|
|
|
|
- name: upload-build
|
|
uses: actions/upload-artifact@master
|
|
with:
|
|
name: html-output
|
|
path: html-output.tar.xz
|
|
|
|
doc-build-pdf:
|
|
name: "Documentation Build (PDF)"
|
|
runs-on: ubuntu-latest
|
|
container: texlive/texlive:latest
|
|
|
|
steps:
|
|
- name: checkout
|
|
uses: actions/checkout@v2
|
|
|
|
- name: install-pkgs
|
|
run: |
|
|
apt-get update
|
|
apt-get install -y python3-pip ninja-build doxygen graphviz librsvg2-bin
|
|
|
|
- name: cache-pip
|
|
uses: actions/cache@v1
|
|
with:
|
|
path: ~/.cache/pip
|
|
key: pip-${{ hashFiles('scripts/requirements-doc.txt') }}
|
|
|
|
- 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
|
|
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
|
|
uses: actions/upload-artifact@master
|
|
with:
|
|
name: pdf-output
|
|
path: doc/_build/latex/zephyr.pdf
|