Skip to content

Commit 1fc9de2

Browse files
ktaborowskiktaborowski
committed
GHA: add PR documentation build workflow
Extract Sphinx build into reusable documentation_build workflow and call it from publish_documentation before Zoomin upload. Add on-pr_documentation to build doc when doc/** changes, post PR comment with workflow logs, HTML artifact, and optional GitHub Pages preview. Signed-off-by: Krzysztof Taborowski <krzysztof.taborowski@nordicsemi.no>
1 parent e063ac5 commit 1fc9de2

3 files changed

Lines changed: 157 additions & 45 deletions

File tree

‎.github/workflows/documentation_build.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Build documentation
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
documentation_tag:
7+
type: string
8+
required: false
9+
default: "latest"
10+
description: "Label stamped into built documentation"
11+
12+
workflow_call:
13+
inputs:
14+
documentation_tag:
15+
type: string
16+
required: true
17+
default: "latest"
18+
19+
jobs:
20+
build:
21+
name: Build documentation
22+
runs-on: ubuntu-24.04
23+
env:
24+
ARCHIVE: "addon-sidewalk_${{ inputs.documentation_tag }}.zip"
25+
container:
26+
image: ghcr.io/nrfconnect/sdk-sidewalk:main
27+
options: --cpus 2
28+
defaults:
29+
run:
30+
shell: nrfutil toolchain-manager launch --install-dir /root/ncs bash -- {0}
31+
32+
steps:
33+
- name: Checkout
34+
uses: actions/checkout@v4
35+
with:
36+
fetch-depth: 0
37+
path: sidewalk
38+
39+
- name: Build documentation
40+
run: |
41+
cd sidewalk/doc
42+
./build_local.sh
43+
44+
cp custom.properties build/html
45+
sed -i 's/__VERSION__/'"${{ inputs.documentation_tag }}"'/g' build/html/custom.properties
46+
47+
cp tags.yml build/html
48+
sed -i 's/__VERSION__/'"${{ inputs.documentation_tag }}"'/g' build/html/tags.yml
49+
50+
cd build/html
51+
zip -rq "${{ env.ARCHIVE }}" .
52+
mv "${{ env.ARCHIVE }}" /workdir/${{ env.ARCHIVE }}
53+
ls -lah /workdir
54+
55+
- name: Upload documentation archive
56+
uses: actions/upload-artifact@v4
57+
with:
58+
name: documentation
59+
path: /workdir/${{ env.ARCHIVE }}
60+
61+
- name: Upload documentation HTML
62+
uses: actions/upload-artifact@v4
63+
with:
64+
name: documentation-html
65+
path: sidewalk/doc/build/html

‎.github/workflows/on-pr_documentation.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Build documentation on PR
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'doc/**'
7+
8+
concurrency:
9+
group: docs-pr-${{ github.event.pull_request.number }}
10+
cancel-in-progress: true
11+
12+
jobs:
13+
build_documentation:
14+
uses: ./.github/workflows/documentation_build.yml
15+
with:
16+
documentation_tag: pr-${{ github.event.pull_request.number }}
17+
18+
post_pr_comment:
19+
name: Post documentation build result
20+
needs: build_documentation
21+
runs-on: ubuntu-24.04
22+
permissions:
23+
pull-requests: write
24+
contents: write
25+
26+
steps:
27+
- name: Download documentation HTML
28+
uses: actions/download-artifact@v4
29+
with:
30+
name: documentation-html
31+
path: doc-preview
32+
33+
- name: Deploy PR preview to GitHub Pages
34+
id: pages
35+
continue-on-error: true
36+
if: github.event.pull_request.head.repo.full_name == github.repository
37+
uses: JamesIves/github-pages-deploy-action@v4
38+
with:
39+
folder: doc-preview
40+
target-folder: previews/pr-${{ github.event.pull_request.number }}
41+
branch: gh-pages
42+
clean: false
43+
single-commit: true
44+
45+
- name: Set preview link
46+
id: preview
47+
run: |
48+
if [ "${{ steps.pages.outcome }}" = "success" ]; then
49+
echo "link=https://nrfconnect.github.io/sdk-sidewalk/previews/pr/${{ github.event.pull_request.number }}/index.html" >> "$GITHUB_OUTPUT"
50+
else
51+
echo "link=Preview deploy skipped or unavailable (fork PR or GitHub Pages not configured)." >> "$GITHUB_OUTPUT"
52+
fi
53+
54+
- name: Write PR comment
55+
uses: peter-evans/create-or-update-comment@v4
56+
with:
57+
issue-number: ${{ github.event.pull_request.number }}
58+
comment-author: github-actions[bot]
59+
body-includes: "<!-- documentation-build -->"
60+
body: |
61+
<!-- documentation-build -->
62+
### Documentation build
63+
64+
Sphinx documentation built successfully for this PR.
65+
66+
| Resource | Link |
67+
| --- | --- |
68+
| Workflow run (build logs) | [${{ github.workflow }} #${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) |
69+
| HTML artifact | [Download `documentation-html`](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}#artifacts) (extract and open `index.html` locally) |
70+
| Browser preview | ${{ steps.preview.outputs.link }} |

‎.github/workflows/publish_documentation.yml‎

Lines changed: 22 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -29,67 +29,44 @@ on:
2929
default: true
3030

3131
jobs:
32-
Publish_Documentation:
33-
env:
34-
ARCHIVE: "addon-sidewalk_${{inputs.documentation_tag}}.zip"
32+
build:
33+
uses: ./.github/workflows/documentation_build.yml
34+
with:
35+
documentation_tag: ${{ inputs.documentation_tag }}
3536

37+
publish:
38+
name: Publish documentation to Zoomin
39+
needs: build
40+
if: inputs.publish_to_dev || inputs.publish_to_prod
3641
runs-on: ubuntu-24.04
37-
container:
38-
image: ghcr.io/nrfconnect/sdk-sidewalk:main
39-
options: --cpus 2
40-
defaults:
41-
run:
42-
shell: nrfutil toolchain-manager launch --install-dir /root/ncs bash -- {0}
42+
env:
43+
ARCHIVE: "addon-sidewalk_${{ inputs.documentation_tag }}.zip"
4344

4445
steps:
45-
- name: Checkout
46-
uses: actions/checkout@v4
47-
with:
48-
fetch-depth: 0
49-
path: sidewalk
50-
51-
- name: Build documentation
52-
run: |
53-
cd sidewalk/doc
54-
./build_local.sh
55-
56-
cp custom.properties build/html
57-
sed -i 's/__VERSION__/'"${{inputs.documentation_tag}}"'/g' build/html/custom.properties
58-
59-
cp tags.yml build/html
60-
sed -i 's/__VERSION__/'"${{inputs.documentation_tag}}"'/g' build/html/tags.yml
61-
62-
cd build/html
63-
zip -rq "${{env.ARCHIVE}}" .
64-
mv "${{env.ARCHIVE}}" /workdir/${{env.ARCHIVE}}
65-
ls -lah /workdir
66-
67-
- name: Upload build artifacts
68-
uses: actions/upload-artifact@v4
46+
- name: Download documentation archive
47+
uses: actions/download-artifact@v4
6948
with:
7049
name: documentation
71-
path: |
72-
/workdir/${{env.ARCHIVE}}
7350

7451
- name: Prepare Key
7552
run: |
76-
mkdir -p /root/.ssh
77-
ssh-keyscan ${{ vars.NCS_ZOOMIN_SERVER }} >> /root/.ssh/known_hosts
53+
mkdir -p ~/.ssh
54+
ssh-keyscan ${{ vars.NCS_ZOOMIN_SERVER }} >> ~/.ssh/known_hosts
7855
echo "${{ secrets.NCS_ZOOMIN_KEY }}" > zoomin_key
7956
chmod 600 zoomin_key
8057
8158
- name: Publish documentation - dev
82-
if: ${{inputs.publish_to_dev}}
59+
if: inputs.publish_to_dev
8360
run: |
84-
sftp -v -i zoomin_key ${{vars.NCS_ZOOMIN_USER}}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
85-
cd ${{ vars.NCS_ZOOMIN_DEPLOY_DEV_PATH}}
86-
put /workdir/${{env.ARCHIVE}}
61+
sftp -v -i zoomin_key ${{ vars.NCS_ZOOMIN_USER }}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
62+
cd ${{ vars.NCS_ZOOMIN_DEPLOY_DEV_PATH }}
63+
put ${{ env.ARCHIVE }}
8764
EOF
8865
8966
- name: Publish documentation - prod
90-
if: ${{inputs.publish_to_prod}}
67+
if: inputs.publish_to_prod
9168
run: |
92-
sftp -v -i zoomin_key ${{vars.NCS_ZOOMIN_USER}}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
93-
cd ${{ vars.NCS_ZOOMIN_DEPLOY_PROD_PATH}}
94-
put /workdir/${{env.ARCHIVE}}
69+
sftp -v -i zoomin_key ${{ vars.NCS_ZOOMIN_USER }}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
70+
cd ${{ vars.NCS_ZOOMIN_DEPLOY_PROD_PATH }}
71+
put ${{ env.ARCHIVE }}
9572
EOF

0 commit comments

Comments
 (0)