Skip to content

Commit 615db10

Browse files
divipillaidivipillai
committed
doc: Update the doc workflow for the new doc platform
Update the doc workflow for the new doc platform Signed-off-by: divya pillai <divya.pillai@nordicsemi.no>
1 parent f436aad commit 615db10

5 files changed

Lines changed: 209 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-and-publish.yml‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
name: Documentation Build and Publish
2+
3+
permissions:
4+
contents: read
5+
6+
on:
7+
pull_request:
8+
types: [opened, synchronize, reopened]
9+
branches:
10+
- main
11+
- 'v*-branch'
12+
paths:
13+
- '.github/workflows/doc-build-and-publish.yml'
14+
- '**.rst'
15+
- 'doc/**'
16+
push:
17+
branches:
18+
- main
19+
- 'v*-branch'
20+
tags:
21+
- v*
22+
23+
env:
24+
DOXYGEN_VERSION: 1.12.0
25+
26+
concurrency:
27+
group: ${{ github.workflow }}-${{ github.ref }}
28+
cancel-in-progress: true
29+
30+
jobs:
31+
doc-build-and-publish:
32+
env:
33+
ARCHIVE: "addon-serial_modem-${{inputs.documentation_tag}}.zip"
34+
35+
runs-on: ubuntu-latest
36+
37+
permissions:
38+
contents: write
39+
40+
steps:
41+
- name: Checkout code
42+
uses: actions/checkout@v4
43+
44+
- name: Install dependencies
45+
run: |
46+
sudo apt-get update
47+
sudo apt-get install -y python3 python3-pip
48+
49+
- name: Install Python dependencies
50+
working-directory: doc
51+
run: |
52+
python3 -m pip install -r requirements.txt
53+
54+
- name: Install Doxygen
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: Build documentation
61+
working-directory: doc
62+
run: |
63+
doxygen
64+
sphinx-build -M html . build
65+
66+
cp custom.properties build/html
67+
sed -i 's/__VERSION__/'"${{inputs.documentation_tag}}"'/g' build/html/custom.properties
68+
69+
cp tags.yml build/html
70+
sed -i 's/__VERSION__/'"${{inputs.documentation_tag}}"'/g' build/html/tags.yml
71+
72+
cd build/html
73+
74+
zip -rq "${{env.ARCHIVE}}" .
75+
ls -lah .
76+
77+
- name: Check version
78+
run: |
79+
VERSION_REGEX="^v([0-9a-zA-Z\.\-]+)$"
80+
if [[ ${GITHUB_REF#refs/tags/} =~ $VERSION_REGEX ]]; then
81+
VERSION=${BASH_REMATCH[1]}
82+
elif [[ ${GITHUB_REF#refs/heads/} == "main" ]]; then
83+
VERSION="latest"
84+
elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
85+
VERSION="pr-${{ github.event.number }}"
86+
fi
87+
echo "VERSION=${VERSION}"
88+
echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
89+
90+
- name: Prepare Azure upload
91+
working-directory: ncs-serial-modem
92+
run: |
93+
PUBLISH="$PWD/publish"
94+
mkdir -p "$PUBLISH"
95+
96+
MONITOR="monitor_${{ github.run_id }}.txt"
97+
98+
# Create documentation upload files
99+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
100+
ARCHIVE="legacy-addon-serial-modem-pr-${{ github.event.number }}.zip"
101+
echo "publish2 dev PR-${{ github.event.number }} ${ARCHIVE}" > "${MONITOR}"
102+
echo "${{ github.event.number }}" > pr.txt
103+
else
104+
ARCHIVE="legacy-addon-serial-modem-${VERSION}.zip"
105+
echo "publish2 main ${VERSION} ${ARCHIVE}" > "${MONITOR}"
106+
fi
107+
108+
pushd "doc/_build/html"
109+
zip -rq "${ARCHIVE}" .
110+
mv "${ARCHIVE}" "$PUBLISH"
111+
popd
112+
113+
mv "${MONITOR}" "$PUBLISH"
114+
if [[ -f pr.txt ]]; then mv pr.txt "$PUBLISH"; fi
115+
116+
- name: Unzip html archive
117+
working-directory: docs
118+
run: |
119+
OUTDIR=$(awk 'NR==1 { if ($3 ~ /^(latest|PR-[0-9]+|[0-9]+\.[0-9a-zA-Z\.\-]+)$/) print $3 }' monitor_*.txt)
120+
echo "OUTDIR=$OUTDIR" >> "$GITHUB_ENV"
121+
unzip legacy-addon-serial-modem*.zip -d $OUTDIR
122+
find "$OUTDIR" -type l -delete
123+
124+
- name: Obtain PR number
125+
if: ${{ github.event.workflow_run.event == 'pull_request' }}
126+
working-directory: docs
127+
run: |
128+
if [ -f pr.txt ]; then
129+
PR=$(head -n 1 pr.txt | tr -cd '0-9')
130+
fi
131+
printf 'PR=%s\n' "$PR" >> "$GITHUB_ENV"
132+
133+
- name: Upload to Azure storage
134+
working-directory: docs
135+
env:
136+
AZCOPY_CONCURRENCY_VALUE: 1024
137+
NCS_DOC_SAS_PRS: ${{ secrets.NCS_DOC_SAS_PRS }}
138+
NCS_DOC_SAS_MAIN: ${{ secrets.NCS_DOC_SAS_MAIN }}
139+
run: |
140+
if [[ "${{ github.event.workflow_run.event }}" == "pull_request" ]]; then
141+
azcopy cp $OUTDIR "${{ vars.NCS_DOC_PR_STORAGE_URL }}addons/serial-modem?$NCS_DOC_SAS_PRS" --recursive=true
142+
else
143+
azcopy cp $OUTDIR "${{ vars.NCS_DOC_STORAGE_URL }}addons/serial-modem?$NCS_DOC_SAS_MAIN" --recursive=true
144+
fi
145+
146+
- name: Upload artifact
147+
uses: actions/upload-artifact@v4
148+
with:
149+
name: doc-build
150+
if-no-files-found: error
151+
retention-days: 2
152+
path: |
153+
doc/build/html/${{env.ARCHIVE}}
154+
155+
- name: Prepare Key
156+
run: |
157+
mkdir -p ~/.ssh
158+
ssh-keyscan upload-v1.zoominsoftware.io >> ~/.ssh/known_hosts
159+
160+
echo "${{ secrets.ZOOMIN_KEY }}" > zoomin_key
161+
chmod 600 zoomin_key
162+
163+
- name: Publish documentation - prod
164+
if: ${{inputs.publish_to_prod}}
165+
run: |
166+
sftp -v -i zoomin_key nordic@upload-v1.zoominsoftware.io <<EOF
167+
cd docs-be.nordicsemi.com/sphinx-html/incoming
168+
put doc/build/html/${{env.ARCHIVE}}
169+
EOF
170+
171+
- name: Publish documentation - dev
172+
if: ${{inputs.publish_to_dev}}
173+
run: |
174+
sftp -v -i zoomin_key nordic@upload-v1.zoominsoftware.io <<EOF
175+
cd nordic-be-dev.zoominsoftware.io/sphinx-html/incoming
176+
put doc/build/html/${{env.ARCHIVE}}
177+
EOF
178+
179+
- name: Find Comment
180+
if: ${{ github.event.workflow_run.event == 'pull_request' }}
181+
uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3
182+
id: fc
183+
with:
184+
issue-number: ${{ env.PR }}
185+
comment-author: 'github-actions[bot]'
186+
body-includes: documentation preview
187+
188+
- name: Create or update comment
189+
if: ${{ github.event.workflow_run.event == 'pull_request' }}
190+
uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4
191+
with:
192+
comment-id: ${{ steps.fc.outputs.comment-id }}
193+
issue-number: ${{ env.PR }}
194+
body: |
195+
You can find the documentation preview for this PR [here](${{ vars.NCS_DOC_PR_HOSTING_URL }}addons/serial-modem/PR-${{ env.PR }}/).
196+
edit-mode: replace

‎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

‎doc/requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Sphinx==5.3.0
22
breathe==4.35.0
3-
sphinx-ncs-theme==0.7.4
3+
sphinx-ncs-theme<1.1
44
sphinx-tabs>=3.4
55
sphinx-togglebutton>=0.3.2
66
Pillow>=9.0.1

‎doc/versions.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[
2+
"2.0.99",
3+
"2.0.0-preview1",
4+
"1.0.1",
5+
"1.0.0",
6+
"0.3.0"
7+
]

0 commit comments

Comments
 (0)