Repository navigation
94 lines (89 loc) · 3.64 KB
/
Copy pathdocs.yml
File metadata and controls
94 lines (89 loc) · 3.64 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Junior Deogracias
#
# This file is part of EmbLinkRTOS, a deterministic real-time kernel for microcontrollers.
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
name: Documentation
on:
push:
branches: [main]
pull_request:
merge_group: # the merge queue tests a pull request on the latest main before merging it
workflow_dispatch:
inputs:
publish:
description: Publish site (requires GitHub Pages source set to GitHub Actions)
type: boolean
default: false
permissions:
contents: read
jobs:
build:
name: Documentation build
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.12'
cache: pip
cache-dependency-path: docs/requirements.txt
# Doxygen's release archive, cached by version: downloaded only when the cache has none, so
# GitHub's release downloads failing does not fail the build; bootstrap.py checks its SHA-512
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ~/.cache/emb-downloads
key: doxygen-${{ hashFiles('tools/docs/bootstrap.py') }}
- name: Install documentation dependencies
env:
GH_TOKEN: ${{ github.token }}
run: |
python -m pip install -r docs/requirements.txt
archive="$HOME/.cache/emb-downloads/doxygen.linux.bin.tar.gz"
url=$(python -c "import sys; sys.path.insert(0, 'tools/docs'); import bootstrap; print(bootstrap.URL)")
# .../releases/download/<tag>/<name>: authenticated first (GitHub has throttled
# unauthenticated downloads), then plain HTTPS
tag=$(basename "$(dirname "$url")")
fetch() { gh release download "$tag" --repo doxygen/doxygen --pattern "$(basename "$url")" \
--output "$archive" --clobber ||
curl -fsSL --retry 6 --retry-all-errors --retry-delay 10 -o "$archive" "$url"; }
mkdir -p "$(dirname "$archive")"
[ -f "$archive" ] || fetch
python tools/docs/bootstrap.py --archive "$archive" || {
rm -f "$archive" # a damaged cached copy is fetched again
fetch
python tools/docs/bootstrap.py --archive "$archive"
}
- name: Build complete documentation with warnings as errors
run: |
python -m unittest discover -s tools/docs -p 'test_*.py' -v
python tools/docs/build.py
- name: Check source preservation
run: git diff --exit-code
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: documentation
path: |
build/docs/html/
build/docs/catalog/
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
if: github.event_name == 'workflow_dispatch' && inputs.publish
with:
path: build/docs/html
deploy:
if: github.event_name == 'workflow_dispatch' && inputs.publish
needs: build
runs-on: ubuntu-24.04
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
concurrency:
group: documentation-pages
cancel-in-progress: false
steps:
- name: Publish reviewed documentation
id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1