Skip to content

Commit d01e17b

Browse files
jcfrjcfr
committed
ci: Add GitHub Workflow to build and publish documentation
1 parent 7714c1a commit d01e17b

File tree

1 file changed

+185
-0
lines changed

1 file changed

+185
-0
lines changed

‎.github/workflows/build-and-publish-doxygen.yml

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
name: Build and Publish
2+
3+
on:
4+
# Allows running this workflow manually from the Actions tab
5+
workflow_dispatch:
6+
inputs:
7+
ref:
8+
description: "Slicer branch or tag for which to build and publish the documentation"
9+
required: true
10+
11+
permissions:
12+
# Needed in the publish step to update gh-pages branch
13+
contents: write
14+
15+
jobs:
16+
build-and-publish:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Collect Inputs
20+
id: collect_inputs
21+
run: |
22+
echo "EVENT_NAME [$EVENT_NAME]"
23+
if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
24+
ref=${{ github.event.inputs.ref }}
25+
else
26+
echo "::error ::Unsupported EVENT_NAME [$EVENT_NAME]"
27+
exit 1
28+
fi
29+
echo "ref=$ref" >> $GITHUB_OUTPUT
30+
env:
31+
EVENT_NAME: ${{ github.event_name }}
32+
33+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
34+
with:
35+
repository: Slicer/Slicer
36+
path: Slicer
37+
ref: ${{ steps.collect_inputs.outputs.ref }}
38+
39+
40+
- name: Determine if ref is branch or tag
41+
id: determine
42+
run:
43+
cd Slicer
44+
45+
if git show-ref -q --verify "refs/heads/$SLICER_REPO_REF" 2>/dev/null; then
46+
echo "slicer_repo_branch=$SLICER_REPO_REF" >> $GITHUB_OUTPUT
47+
exit 0
48+
49+
elif git show-ref -q --verify "refs/tags/$SLICER_REPO_REF" 2>/dev/null; then
50+
echo "slicer_repo_tag=$SLICER_REPO_REF" >> $GITHUB_OUTPUT
51+
exit 0
52+
53+
elif git show-ref -q --verify "refs/remote/$SLICER_REPO_REF" 2>/dev/null; then
54+
echo "::error ::Specifying reference as remote [$SLICER_REPO_REF] is not supported"
55+
exit 1
56+
57+
elif git rev-parse --verify "$SLICER_REPO_REF^{commit}" >/dev/null 2>&1; then
58+
echo "::error ::Specifying reference as remote [$SLICER_REPO_REF] is not supported"
59+
exit 1
60+
61+
else
62+
echo "unknown"
63+
exit 1
64+
65+
fi
66+
env:
67+
SLICER_REPO_REF: ${{ steps.collect_inputs.outputs.ref }}
68+
69+
- uses: ssciwr/doxygen-install@527824132256e685f03ec80c0851fe79937eb1d6 # v1.6.3
70+
with:
71+
version: "1.10.0"
72+
73+
# The "dot" binary is provided by Graphviz
74+
- uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
75+
76+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
77+
with:
78+
repository: Slicer/slicer-apidocs-builder
79+
path: slicer-apidocs-builder
80+
ref: 1744509e91fa66186d34e4c6968ee684131c51d1
81+
82+
- uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
83+
with:
84+
python-version: '3.13'
85+
cache: 'pip'
86+
87+
- name: Install slicer-apidocs-builder
88+
run: |
89+
pip install ./slicer-apidocs-builder
90+
91+
- name: Generate Documentation
92+
id: generate
93+
run: |
94+
WARNING_LOG_FILE=/tmp/Slicer-Slicer-$SLICER_REPO_BRANCH-build/Utilities/Doxygen/UserDoxygenWarnings.txt
95+
mkdir -p $(dirname $WARNING_LOG_FILE)
96+
97+
slicer-apidocs-builder \
98+
--skip-publish \
99+
--slicer-repo-dir $(pwd)/Slicer \
100+
--slicer-repo-branch "$SLICER_REPO_BRANCH" \
101+
--slicer-repo-tag "${SLICER_REPO_TAG}" 2> >(tee $WARNING_LOG_FILE >&2)
102+
103+
echo "warning_log_file=$WARNING_LOG_FILE" >> $GITHUB_OUTPUT
104+
env:
105+
SLICER_REPO_BRANCH: ${{ steps.determine.outputs.slicer_repo_branch }}
106+
SLICER_REPO_TAG: ${{ steps.determine.outputs.slicer_repo_tag }}
107+
108+
- name: Parse and annotate Doxygen warnings
109+
run: |
110+
echo "WARNING_LOG_FILE [$WARNING_LOG_FILE]"
111+
if [[ -f $WARNING_LOG_FILE ]]; then
112+
buffer=""
113+
while IFS= read -r line || [[ -n "$line" ]]; do
114+
# If a buffer exists, prepend the buffered line to this line
115+
if [[ -n "$buffer" ]]; then
116+
line="$buffer$line"
117+
buffer=""
118+
fi
119+
120+
# Extract file, line number, and warning message
121+
FILE=$(echo "$line" | grep -oP "^[^:]+" || true)
122+
LINE=$(echo "$line" | grep -oP ":(\d+):" | tr -d ":" || true)
123+
MESSAGE=$(echo "$line" | grep -oP "warning:.*" || true)
124+
125+
# If MESSAGE is found, process further
126+
if [[ -n "$MESSAGE" ]]; then
127+
MESSAGE=${MESSAGE#warning: } # Strip "warning: " prefix
128+
129+
# Aggregate all subsequent lines starting with at least a space
130+
while IFS= read -r continuation || [[ -n "$continuation" ]]; do
131+
if [[ "$continuation" =~ ^[[:space:]] ]]; then
132+
MESSAGE="${MESSAGE}%0A${continuation}"
133+
else
134+
# Buffer the line to be processed in the main loop
135+
buffer="$continuation"
136+
break
137+
fi
138+
done
139+
fi
140+
141+
# Annotate in GitHub Actions
142+
if [[ -n "$FILE" && -n "$LINE" && -n "$MESSAGE" ]]; then
143+
echo "::warning file=$FILE,line=$LINE::$MESSAGE"
144+
elif [[ -n "$MESSAGE" ]]; then
145+
echo "::warning ::$MESSAGE"
146+
else
147+
echo "Skipped unmatched line: $line"
148+
fi
149+
150+
done < "$WARNING_LOG_FILE"
151+
else
152+
echo "No Doxygen warnings log found."
153+
fi
154+
env:
155+
WARNING_LOG_FILE: ${{ steps.generate.outputs.warning_log_file }}
156+
157+
- uses: actions/create-github-app-token@c1a285145b9d317df6ced56c09f525b5c2b6f755 # v1.11.1
158+
id: app-token
159+
with:
160+
app-id: ${{ vars.SLICER_APP_ID }}
161+
private-key: ${{ secrets.SLICER_APP_PRIVATE_KEY }}
162+
163+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
164+
with:
165+
ref: gh-pages
166+
path: gh-pages
167+
token: ${{ steps.app-token.outputs.token }}
168+
169+
- name: Publish documentation
170+
run: |
171+
slicer-apidocs-builder \
172+
--skip-build \
173+
--slicer-repo-dir $(pwd)/Slicer \
174+
--slicer-repo-name ${SLICER_REPO_NAME} \
175+
--slicer-repo-branch "${SLICER_REPO_BRANCH}" \
176+
--slicer-repo-tag "${SLICER_REPO_TAG}" \
177+
--publish-github-repo-name "Slicer/${PUBLISH_GITHUB_PROJECT_NAME}" \
178+
--publish-github-repo-branch gh-pages
179+
env:
180+
PUBLISH_GITHUB_PROJECT_NAME: apidocs.slicer.org
181+
PUBLISH_GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
182+
SLICER_REPO_NAME: Slicer/Slicer
183+
SLICER_REPO_BRANCH: ${{ steps.determine.outputs.slicer_repo_branch }}
184+
SLICER_REPO_TAG: ${{ steps.determine.outputs.slicer_repo_tag }}
185+

0 commit comments

Comments
 (0)