Skip to content

Commit 6bf73a8

Browse files
kg-nordicsemikg-nordicsemi
committed
docs: Integrate Aliro docs with Zoomin
- Add doc_build.yml workflow for building docs, preparing Azure and Zoomin upload artifacts. - Add doc_publish.yml workflow for publishing docs to Azure Storage and Zoomin using SFTP. - Add doc_remove.yml workflow for cleaning up PR preview docs from Azure Storage. - Add _zoomin/aliro.custom.properties and _zoomin/aliro.tags.yml for Zoomin metadata. Signed-off-by: Konrad Grucel <konrad.grucel@nordicsemi.no>
1 parent ec0df88 commit 6bf73a8

11 files changed

Lines changed: 403 additions & 0 deletions

‎.github/workflows/doc_build.yml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
name: Documentation Build
2+
3+
permissions:
4+
contents: read
5+
6+
on:
7+
pull_request:
8+
types: [opened, synchronize, reopened]
9+
branches:
10+
- main
11+
paths:
12+
- '.github/workflows/doc_build.yml'
13+
- '**.rst'
14+
- 'docs/**'
15+
push:
16+
branches:
17+
- main
18+
tags:
19+
- v*
20+
21+
concurrency:
22+
group: ${{ github.workflow }}-${{ github.ref }}
23+
cancel-in-progress: true
24+
25+
jobs:
26+
build:
27+
runs-on: ubuntu-24.04
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
31+
with:
32+
ref: ${{ github.event.pull_request.head.sha }}
33+
34+
- name: Set up Python
35+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
36+
with:
37+
python-version: 3.12
38+
cache: pip
39+
cache-dependency-path: docs/requirements.txt
40+
pip-install: |
41+
-r docs/requirements.txt
42+
43+
- name: Build
44+
working-directory: docs
45+
run: make html
46+
47+
- name: Check version
48+
run: |
49+
VERSION_REGEX="^v([0-9a-zA-Z\.\-]+)$"
50+
if [[ ${GITHUB_REF#refs/tags/} =~ $VERSION_REGEX ]]; then
51+
VERSION=${BASH_REMATCH[1]}
52+
elif [[ ${GITHUB_REF#refs/heads/} == "main" ]]; then
53+
VERSION="latest"
54+
elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
55+
VERSION="pr-${{ github.event.number }}"
56+
fi
57+
echo "VERSION=${VERSION}"
58+
echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
59+
60+
- name: Prepare Azure upload
61+
run: |
62+
PUBLISH="$PWD/publish"
63+
mkdir -p "$PUBLISH"
64+
65+
MONITOR="monitor_${{ github.run_id }}.txt"
66+
67+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
68+
ARCHIVE="legacy-addon-aliro-pr-${{ github.event.number }}.zip"
69+
echo "publish2 dev PR-${{ github.event.number }} ${ARCHIVE}" > "${MONITOR}"
70+
echo "${{ github.event.number }}" > pr.txt
71+
else
72+
ARCHIVE="legacy-addon-aliro-${VERSION}.zip"
73+
echo "publish2 main ${VERSION} ${ARCHIVE}" > "${MONITOR}"
74+
fi
75+
76+
pushd "docs/build/html"
77+
zip -rq "${ARCHIVE}" .
78+
mv "${ARCHIVE}" "$PUBLISH"
79+
popd
80+
81+
mv "${MONITOR}" "$PUBLISH"
82+
if [[ -f pr.txt ]]; then mv pr.txt "$PUBLISH"; fi
83+
84+
- name: Prepare Zoomin upload
85+
if: ${{ github.event_name == 'push' }}
86+
run: |
87+
PUBLISH="$PWD/publish"
88+
mkdir -p "$PUBLISH"
89+
90+
OUTDIR=docs/build/html
91+
ARCHIVE="addon-aliro_$VERSION.zip"
92+
93+
cp docs/_zoomin/aliro.custom.properties "$OUTDIR/custom.properties"
94+
sed -i 's/__VERSION__/'"$VERSION"'/g' "$OUTDIR/custom.properties"
95+
96+
cp docs/_zoomin/aliro.tags.yml "$OUTDIR/tags.yml"
97+
sed -i 's/__VERSION__/'"$VERSION"'/g' "$OUTDIR/tags.yml"
98+
99+
pushd "$OUTDIR"
100+
zip -rq "$ARCHIVE" .
101+
mv "$ARCHIVE" "$PUBLISH"
102+
popd
103+
104+
- name: Store
105+
if: ${{ !contains(github.event.pull_request.labels.*.name, 'external') || contains(github.event.pull_request.labels.*.name, 'CI-trusted-author') }}
106+
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
107+
with:
108+
name: docs
109+
retention-days: 5
110+
path: |
111+
publish/*

‎.github/workflows/doc_publish.yml‎

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

‎.github/workflows/on_push_publish_documentation.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Publish latest documentation
2+
3+
on:
4+
workflow_dispatch:
5+
6+
push:
7+
branches:
8+
- main
9+
paths:
10+
- 'docs/**'
11+
12+
jobs:
13+
deploy:
14+
uses: ./.github/workflows/publish_documentation.yaml
15+
with:
16+
documentation_tag: "latest"
17+
publish_to_prod: true
18+
publish_to_dev: true
19+
secrets:
20+
NCS_ZOOMIN_KEY: ${{ secrets.NCS_ZOOMIN_KEY }}

‎.github/workflows/on_push_tag.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: Publish release documentation
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v[0-9]+.[0-9]+.[0-9]+*'
7+
8+
jobs:
9+
build_documentation:
10+
uses: ./.github/workflows/publish_documentation.yaml
11+
secrets:
12+
NCS_ZOOMIN_KEY: ${{ secrets.NCS_ZOOMIN_KEY }}
13+
with:
14+
documentation_tag: ${{ github.ref_name }}
15+
publish_to_prod: true
16+
publish_to_dev: true

‎.github/workflows/publish_documentation.yaml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
name: Publish documentation
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
documentation_tag:
7+
type: string
8+
required: false
9+
default: "latest"
10+
description: "Label of the documentation"
11+
publish_to_prod:
12+
type: boolean
13+
default: true
14+
publish_to_dev:
15+
type: boolean
16+
default: true
17+
18+
workflow_call:
19+
inputs:
20+
documentation_tag:
21+
type: string
22+
required: true
23+
default: "latest"
24+
publish_to_prod:
25+
type: boolean
26+
default: true
27+
publish_to_dev:
28+
type: boolean
29+
default: true
30+
secrets:
31+
NCS_ZOOMIN_KEY:
32+
required: true
33+
34+
jobs:
35+
Publish_Documentation:
36+
env:
37+
DOCS_DIR: docs
38+
DOC_TAG: ${{ inputs.documentation_tag }}
39+
40+
runs-on: ubuntu-24.04
41+
42+
steps:
43+
- name: Checkout
44+
uses: actions/checkout@v4
45+
with:
46+
fetch-depth: 0
47+
48+
- name: Set up Python
49+
uses: actions/setup-python@v5
50+
with:
51+
python-version: '3.12'
52+
53+
- name: Build documentation
54+
env:
55+
ARCHIVE: "addon-aliro_${{ env.DOC_TAG }}.zip"
56+
run: |
57+
cd ${{env.DOCS_DIR}}
58+
./generate_docs.sh
59+
60+
cp custom.properties build/html/
61+
sed -i "s/__VERSION__/${DOC_TAG}/g" build/html/custom.properties
62+
63+
cp tags.yml build/html/
64+
sed -i "s/__VERSION__/${DOC_TAG}/g" build/html/tags.yml
65+
66+
cd build/html
67+
zip -rq "${ARCHIVE}" .
68+
69+
- name: Upload build artifacts
70+
uses: actions/upload-artifact@v4
71+
with:
72+
name: documentation
73+
path: ${{env.DOCS_DIR}}/build/html/addon-aliro_${{ env.DOC_TAG }}.zip
74+
75+
- name: Prepare Key
76+
env:
77+
NCS_ZOOMIN_KEY: ${{ secrets.NCS_ZOOMIN_KEY }}
78+
run: |
79+
mkdir -p ~/.ssh
80+
ssh-keyscan ${{ vars.NCS_ZOOMIN_SERVER }} >> ~/.ssh/known_hosts
81+
echo "$NCS_ZOOMIN_KEY" > zoomin_key
82+
chmod 600 zoomin_key
83+
84+
- name: Publish documentation - dev
85+
if: ${{ inputs.publish_to_dev }}
86+
env:
87+
ARCHIVE: "addon-aliro_${{ env.DOC_TAG }}.zip"
88+
run: |
89+
sftp -v -i zoomin_key ${{vars.NCS_ZOOMIN_USER}}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
90+
cd ${{ vars.NCS_ZOOMIN_DEPLOY_DEV_PATH}}
91+
put ${{env.DOCS_DIR}}/build/html/${ARCHIVE}
92+
EOF
93+
94+
- name: Publish documentation - prod
95+
if: ${{ inputs.publish_to_prod }}
96+
env:
97+
ARCHIVE: "addon-aliro_${{ env.DOC_TAG }}.zip"
98+
run: |
99+
sftp -v -i zoomin_key ${{vars.NCS_ZOOMIN_USER}}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
100+
cd ${{ vars.NCS_ZOOMIN_DEPLOY_PROD_PATH}}
101+
put ${{env.DOCS_DIR}}/build/html/${ARCHIVE}
102+
EOF

‎docs/_zoomin/aliro.custom.properties‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
manual.name=addon-aliro___VERSION__
2+
booktitle=nRF Door Lock and Access Control Add-on - __VERSION__

‎docs/_zoomin/aliro.tags.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Document tags for Zoomin.
2+
3+
# Tags for all topics:
4+
mapping_global:
5+
- addon-aliro
6+
- addon-aliro___VERSION__
7+
- cluster-addon-aliro___VERSION__
8+
9+
# Tags for individual topics:
10+
mapping_topics: []

‎docs/custom.properties‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
manual.name=addon-aliro-__VERSION__
2+
booktitle=nRF Door Lock and Access Control Add-on __VERSION__

0 commit comments

Comments
 (0)