Skip to content

Commit 7859251

Browse files
divipillaidivipillai
committed
doc: Add doc workflow for new doc platform
Add doc workflow for new doc platform. Signed-off-by: divya pillai <divya.pillai@nordicsemi.no>
1 parent ef45232 commit 7859251

7 files changed

Lines changed: 276 additions & 117 deletions

File tree

‎.github/workflows/doc-build-and-publish-zoomin.yml‎

Lines changed: 0 additions & 116 deletions
This file was deleted.

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

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
name: Documentation Build
2+
3+
permissions:
4+
contents: read
5+
6+
on:
7+
workflow_dispatch:
8+
inputs:
9+
documentation_tag:
10+
type: string
11+
required: false
12+
default: "latest"
13+
description: "Label of the documentation"
14+
publish_to_prod:
15+
type: boolean
16+
default: true
17+
publish_to_dev:
18+
type: boolean
19+
default: true
20+
pull_request:
21+
types: [opened, synchronize, reopened]
22+
branches:
23+
- main
24+
- 'v*-branch'
25+
paths:
26+
- '.github/workflows/doc-build.yml'
27+
- '.github/workflows/doc-publish.yml'
28+
- '**.rst'
29+
- 'doc/**'
30+
- "include/**"
31+
push:
32+
branches:
33+
- main
34+
- 'v*-branch'
35+
tags:
36+
- v*
37+
38+
env:
39+
DOXYGEN_VERSION: 1.12.0
40+
41+
concurrency:
42+
group: ${{ github.workflow }}-${{ github.ref }}
43+
cancel-in-progress: true
44+
45+
jobs:
46+
build:
47+
runs-on: ubuntu-24.04
48+
steps:
49+
- name: Checkout
50+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
51+
with:
52+
ref: ${{ github.event.pull_request.head.sha }}
53+
54+
- name: Install system dependencies
55+
run: |
56+
wget --no-verbose "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
57+
sudo tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz -C /opt
58+
echo "/opt/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH
59+
60+
- name: Set up Python
61+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
62+
with:
63+
python-version: 3.12
64+
cache: pip
65+
cache-dependency-path: doc/requirements.txt
66+
pip-install: |
67+
-r doc/requirements.txt
68+
69+
- name: Build
70+
working-directory: doc
71+
run: |
72+
doxygen
73+
sphinx-build -M html . build
74+
75+
- name: Check version
76+
run: |
77+
VERSION_REGEX="^v([0-9a-zA-Z\.\-]+)$"
78+
if [[ ${GITHUB_REF#refs/tags/} =~ $VERSION_REGEX ]]; then
79+
VERSION=${BASH_REMATCH[1]}
80+
elif [[ ${GITHUB_REF#refs/heads/} == "main" ]]; then
81+
VERSION="latest"
82+
elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
83+
VERSION="pr-${{ github.event.number }}"
84+
fi
85+
echo "VERSION=${VERSION}"
86+
echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
87+
88+
- name: Prepare Azure upload
89+
working-directory: doc
90+
run: |
91+
PUBLISH="$PWD/publish"
92+
mkdir -p "$PUBLISH"
93+
94+
MONITOR="monitor_${{ github.run_id }}.txt"
95+
96+
# Create documentation upload files
97+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
98+
ARCHIVE="legacy-addon-serial_modem-pr-${{ github.event.number }}.zip"
99+
echo "publish2 dev PR-${{ github.event.number }} ${ARCHIVE}" > "${MONITOR}"
100+
echo "${{ github.event.number }}" > pr.txt
101+
else
102+
ARCHIVE="legacy-addon-serial_modem-${VERSION}.zip"
103+
echo "publish2 main ${VERSION} ${ARCHIVE}" > "${MONITOR}"
104+
fi
105+
106+
pushd "doc/build/html"
107+
zip -rq "${ARCHIVE}" .
108+
mv "${ARCHIVE}" "$PUBLISH"
109+
popd
110+
111+
mv "${MONITOR}" "$PUBLISH"
112+
if [[ -f pr.txt ]]; then mv pr.txt "$PUBLISH"; fi
113+
114+
- name: Prepare Zoomin upload
115+
if: ${{ github.event_name == 'push' }}
116+
working-directory: doc
117+
run: |
118+
PUBLISH="$PWD/publish"
119+
mkdir -p "$PUBLISH"
120+
121+
OUTDIR=doc/build/html
122+
ARCHIVE="addon-serial_modem_$VERSION.zip"
123+
124+
cp custom.properties "$OUTDIR/custom.properties"
125+
sed -i 's/__VERSION__/'"$VERSION"'/g' "$OUTDIR/custom.properties"
126+
127+
cp tags.yml "$OUTDIR/tags.yml"
128+
sed -i 's/__VERSION__/'"$VERSION"'/g' "$OUTDIR/tags.yml"
129+
130+
pushd "$OUTDIR"
131+
zip -rq "$ARCHIVE" .
132+
mv "$ARCHIVE" "$PUBLISH"
133+
popd
134+
135+
- name: Store
136+
if: ${{ !contains(github.event.pull_request.labels.*.name, 'external') || contains(github.event.pull_request.labels.*.name, 'CI-trusted-author') }}
137+
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
138+
with:
139+
name: docs
140+
retention-days: 5
141+
path: |
142+
publish/*

‎.github/workflows/doc-publish.yml‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
name: Documentation Publish
2+
3+
permissions:
4+
contents: read
5+
pull-requests: write
6+
7+
on:
8+
9+
workflow_run:
10+
workflows: ["Documentation Build"]
11+
types:
12+
- completed
13+
14+
jobs:
15+
publish:
16+
runs-on: ubuntu-24.04
17+
if: ${{ github.event.workflow_run.conclusion == 'success' }}
18+
steps:
19+
- name: Download artifacts
20+
uses: dawidd6/action-download-artifact@bf251b5aa9c2f7eeb574a96ee720e24f801b7c11 # v6
21+
with:
22+
workflow: doc-build.yml
23+
run_id: ${{ github.event.workflow_run.id }}
24+
name: docs
25+
path: doc
26+
27+
- name: Unzip html archive
28+
working-directory: docs
29+
run: |
30+
OUTDIR=$(awk 'NR==1 { if ($3 ~ /^(latest|PR-[0-9]+|[0-9]+\.[0-9a-zA-Z\.\-]+)$/) print $3 }' monitor_*.txt)
31+
echo "OUTDIR=$OUTDIR" >> "$GITHUB_ENV"
32+
unzip legacy-addon-serial_modem*.zip -d $OUTDIR
33+
find "$OUTDIR" -type l -delete
34+
35+
- name: Obtain PR number
36+
if: ${{ github.event.workflow_run.event == 'pull_request' }}
37+
working-directory: docs
38+
run: |
39+
if [ -f pr.txt ]; then
40+
PR=$(head -n 1 pr.txt | tr -cd '0-9')
41+
fi
42+
printf 'PR=%s\n' "$PR" >> "$GITHUB_ENV"
43+
44+
- name: Upload to Azure storage
45+
working-directory: docs
46+
env:
47+
AZCOPY_CONCURRENCY_VALUE: 1024
48+
NCS_DOC_SAS_PRS: ${{ secrets.NCS_DOC_SAS_PRS }}
49+
NCS_DOC_SAS_MAIN: ${{ secrets.NCS_DOC_SAS_MAIN }}
50+
run: |
51+
if [[ "${{ github.event.workflow_run.event }}" == "pull_request" ]]; then
52+
azcopy cp $OUTDIR "${{ vars.NCS_DOC_PR_STORAGE_URL }}addon-serial_modem?$NCS_DOC_SAS_PRS" --recursive=true
53+
else
54+
azcopy cp $OUTDIR "${{ vars.NCS_DOC_STORAGE_URL }}addon-serial_modem?$NCS_DOC_SAS_MAIN" --recursive=true
55+
fi
56+
57+
- name: Upload Zoomin documentation
58+
if: >
59+
github.event.workflow_run.head_branch == 'main' &&
60+
github.event.workflow_run.head_repository.full_name == github.repository
61+
env:
62+
NCS_ZOOMIN_KEY: ${{ secrets.NCS_ZOOMIN_KEY }}
63+
run: |
64+
# trust server
65+
mkdir -p ~/.ssh
66+
ssh-keyscan ${{ vars.NCS_ZOOMIN_SERVER }} >> ~/.ssh/known_hosts
67+
68+
# prepare key
69+
touch zoomin_key
70+
chmod 600 zoomin_key
71+
echo "$NCS_ZOOMIN_KEY" | base64 -d > zoomin_key
72+
73+
# upload files
74+
for file in docs/addon-serial_modem*.zip; do
75+
sftp -v -i zoomin_key ${{ vars.NCS_ZOOMIN_USER }}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
76+
cd docs-be.nordicsemi.com/sphinx-html/incoming
77+
put ${file}
78+
cd ../../../nordic-be-dev.zoominsoftware.io/sphinx-html/incoming
79+
put ${file}
80+
quit
81+
EOF
82+
done
83+
84+
- name: Find Comment
85+
if: ${{ github.event.workflow_run.event == 'pull_request' }}
86+
uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3
87+
id: fc
88+
with:
89+
issue-number: ${{ env.PR }}
90+
comment-author: 'github-actions[bot]'
91+
body-includes: documentation preview
92+
93+
- name: Create or update comment
94+
if: ${{ github.event.workflow_run.event == 'pull_request' }}
95+
uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4
96+
with:
97+
comment-id: ${{ steps.fc.outputs.comment-id }}
98+
issue-number: ${{ env.PR }}
99+
body: |
100+
You can find the documentation preview for this PR [here](${{ vars.NCS_DOC_PR_HOSTING_URL }}addon-serial_modem/PR-${{ env.PR }}/).
101+
edit-mode: replace

‎.github/workflows/doc_remove.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Documentation Remove
2+
3+
permissions:
4+
contents: read
5+
6+
on:
7+
pull_request_target:
8+
types: [closed]
9+
branches:
10+
- main
11+
12+
jobs:
13+
remove:
14+
runs-on: ubuntu-24.04
15+
steps:
16+
- name: Try removal of PR-docs
17+
env:
18+
AZCOPY_CONCURRENCY_VALUE: 3000
19+
run: |
20+
azcopy rm "${{ vars.NCS_DOC_PR_STORAGE_URL }}addon-serial_modem/PR-${{ github.event.number }}?${{ secrets.NCS_DOC_SAS_PRS }}" --recursive=true || true

‎doc/conf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,11 @@
3636
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
3737

3838
html_theme = 'sphinx_ncs_theme'
39+
html_theme_options = {
40+
'docsets': {},
41+
}
42+
43+
html_extra_path = ['versions.json']
3944

4045
## -- Options for Breathe ----------------------------------------------------
4146
# https://breathe.readthedocs.io/en/latest/index.html

0 commit comments

Comments
 (0)