Skip to content

Commit 6b9accd

Browse files
skjnldsvskjnldsv
authored
Merge pull request #14177 from skjnldsv/master
2 parents 0699466 + 3916ae8 commit 6b9accd

66 files changed

Lines changed: 1180 additions & 794 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/generate-top-index.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: "Build documentation index"
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
branches:
9+
- master
10+
11+
permissions:
12+
contents: write
13+
14+
jobs:
15+
build-and-deploy:
16+
name: Build index.html
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Cache git metadata
21+
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
22+
with:
23+
path: .git
24+
key: git-metadata-${{ github.sha }}
25+
restore-keys: |
26+
git-metadata-${{ github.sha }}
27+
git-metadata
28+
29+
- name: Checkout Github Pages branch
30+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
31+
with:
32+
fetch-depth: 0
33+
34+
- name: Get stable branches
35+
id: branch
36+
run: |
37+
branches=$(git ls-remote --heads origin "heads/stable[0-9][0-9]" | awk '{gsub(/^refs\/heads\/stable/, "", $2); print $2}' | sort -n -r | tr '\n' ' ')
38+
echo "branches=$branches" >> $GITHUB_OUTPUT
39+
40+
- name: Setup php
41+
uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # v2.37.0
42+
43+
- name: Generate index.html
44+
run: |
45+
php build/build-index.php ${{ steps.branch.outputs.branches }}
46+
mv build/index.html /tmp/index.html
47+
mv build/static/ /tmp/static/
48+
49+
- name: Verify index.html structure and links
50+
run: |
51+
# Temporarily put index.html in build folder for verification
52+
cp /tmp/index.html build/index.html
53+
php build/verify-index.php
54+
55+
- name: Switch to gh-pages branch
56+
if: github.event_name == 'push'
57+
run: |
58+
git fetch origin gh-pages
59+
git checkout gh-pages
60+
git config --local user.email "action@github.com"
61+
git config --local user.name "GitHub Action"
62+
63+
- name: Commit and push changes
64+
if: github.event_name == 'push'
65+
run: |
66+
# Move the generated index.html and static files to the root of the gh-pages branch
67+
rm -rf index.html static/
68+
mv /tmp/index.html index.html
69+
mv /tmp/static/ static/
70+
git add index.html static/
71+
git commit -m "chore: update index.html for documentation" || echo "No changes to commit"
72+
git push origin gh-pages || echo "Nothing to push (expected if no changes)"

‎.github/workflows/sphinxbuild.yml‎

Lines changed: 219 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -11,94 +11,239 @@ permissions:
1111
contents: read
1212

1313
jobs:
14-
user_manual:
14+
build:
15+
16+
name: Build ${{ matrix.manual.name }}
1517
runs-on: ubuntu-latest
18+
19+
strategy:
20+
matrix:
21+
manual:
22+
- name: "user_manual"
23+
directory: "user_manual"
24+
make_target: "html"
25+
build_path: "_build/html"
26+
build_pdf_path: "_build/latex"
27+
publish: true
28+
29+
- name: "user_manual-en"
30+
directory: "user_manual"
31+
make_target: "html-lang-en"
32+
build_path: "_build/html"
33+
publish: false
34+
35+
- name: "developer_manual"
36+
directory: "developer_manual"
37+
make_target: "html"
38+
build_path: "_build/html/com"
39+
publish: true
40+
41+
- name: "admin_manual"
42+
directory: "admin_manual"
43+
make_target: "html"
44+
build_path: "_build/html/com"
45+
build_pdf_path: "_build/latex"
46+
publish: true
47+
1648
steps:
17-
- name: Checkout
18-
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
49+
- name: Cache git metadata
50+
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
1951
with:
20-
persist-credentials: false
52+
path: .git
53+
key: git-metadata-${{ github.sha }}
54+
restore-keys: |
55+
git-metadata-${{ github.sha }}
56+
git-metadata
57+
58+
- name: Checkout repository
59+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
2160

22-
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
61+
- name: Install LaTeX dependencies
62+
if: ${{ matrix.manual.build_pdf_path }}
63+
run: |
64+
sudo DEBIAN_FRONTEND=noninteractive apt-get update
65+
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
66+
python3-pil \
67+
python3-pip \
68+
texlive-fonts-recommended \
69+
latexmk \
70+
texlive-latex-extra \
71+
texlive-latex-recommended \
72+
texlive-xetex \
73+
texlive-fonts-extra-links \
74+
texlive-fonts-extra \
75+
xindy
76+
77+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
2378
with:
2479
python-version: '3.12'
2580
cache: 'pip'
81+
2682
- name: Install pip dependencies
2783
run: pip install -r requirements.txt
28-
- name: Build using Makefile
29-
run: cd user_manual && make html
30-
- name: Pack the results in local tar file
31-
shell: bash
32-
run: tar czf /tmp/documentation.tar.gz -C user_manual/_build/html .
84+
85+
- name: Build html documentation
86+
run: cd ${{ matrix.manual.directory }} && make ${{ matrix.manual.make_target }}
87+
88+
- name: Compute PDF release version
89+
if: ${{ matrix.manual.build_pdf_path }}
90+
id: pdf_version
91+
run: |
92+
branch="${GITHUB_REF#refs/heads/}"
93+
if [[ "$branch" == stable* ]]; then
94+
echo "release=${branch#stable}" >> $GITHUB_OUTPUT
95+
else
96+
echo "release=latest" >> $GITHUB_OUTPUT
97+
fi
98+
99+
- name: Build pdf documentation
100+
if: ${{ matrix.manual.build_pdf_path }}
101+
env:
102+
DOCS_RELEASE: ${{ steps.pdf_version.outputs.release }}
103+
run: |
104+
set -e
105+
cd ${{ matrix.manual.directory }}
106+
make latexpdf
107+
ls -la ${{ matrix.manual.build_pdf_path }}
108+
cp ${{ matrix.manual.build_pdf_path }}/*.pdf ${{ matrix.manual.build_path }}/
109+
33110
- name: Upload static documentation
34111
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
112+
if: ${{ matrix.manual.publish }}
35113
with:
36-
name: User manual.zip
37-
path: "/tmp/documentation.tar.gz"
114+
name: ${{ matrix.manual.name }}
115+
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
38116

39-
user_manual-en:
40-
runs-on: ubuntu-latest
41-
steps:
42-
- name: Checkout
43-
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
44-
with:
45-
persist-credentials: false
46-
47-
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
48-
with:
49-
python-version: '3.12'
50-
cache: 'pip'
51-
- name: Install pip dependencies
52-
run: pip install -r requirements.txt
53-
- name: Build using Makefile
54-
run: cd user_manual && make html-lang-en
55-
56-
developer_manual:
117+
deploy:
118+
name: Deploy pages
119+
needs: build
57120
runs-on: ubuntu-latest
121+
if: github.event_name == 'push' # Only deploy on push, not PR
122+
123+
permissions:
124+
contents: write
125+
58126
steps:
59-
- name: Checkout
60-
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
61-
with:
62-
persist-credentials: false
63-
64-
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
65-
with:
66-
python-version: '3.12'
67-
cache: 'pip'
68-
- name: Install pip dependencies
69-
run: pip install -r requirements.txt
70-
- name: Build using Makefile
71-
run: cd developer_manual && make html
72-
- name: Pack the results in local tar file
73-
shell: bash
74-
run: tar czf /tmp/documentation.tar.gz -C developer_manual/_build/html/com .
75-
- name: Upload static documentation
76-
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
77-
with:
78-
name: Developer manual.zip
79-
path: "/tmp/documentation.tar.gz"
80-
81-
admin_manual:
127+
- name: Cache git metadata
128+
uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
129+
with:
130+
path: .git
131+
key: git-metadata-${{ github.sha }}
132+
restore-keys: |
133+
git-metadata-${{ github.sha }}
134+
git-metadata
135+
136+
- name: Checkout Github Pages branch
137+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
138+
with:
139+
ref: gh-pages
140+
fetch-depth: 0
141+
142+
- name: Download all ${{ needs.build.outputs.branch_name }} artifacts
143+
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
144+
with:
145+
path: artifacts/
146+
147+
- name: Get branch name and find latest stable
148+
id: branch
149+
run: |
150+
current_branch="${GITHUB_REF#refs/heads/}"
151+
152+
# Find the highest numbered stable branch from the remote
153+
highest_stable=$(git ls-remote --heads origin | sed -n 's?.*refs/heads/stable\([0-9]\{2\}\)$?\1?p' | sort -n | tail -1)
154+
highest_stable_branch="stable${highest_stable}"
155+
156+
echo "Current branch: $current_branch"
157+
echo "Highest stable branch found: $highest_stable_branch"
158+
159+
# Map actual branch names to deployment folder names
160+
case "$current_branch" in
161+
"master")
162+
echo "branch_name=latest" >> $GITHUB_OUTPUT
163+
;;
164+
"$highest_stable_branch")
165+
echo "branch_name=stable" >> $GITHUB_OUTPUT
166+
# Also record the numeric version so we can publish to server/<number>/ too
167+
echo "version_name=${highest_stable}" >> $GITHUB_OUTPUT
168+
;;
169+
*)
170+
# Remove stable prefix for current branch
171+
current_branch="${current_branch#stable}"
172+
echo "branch_name=$current_branch" >> $GITHUB_OUTPUT
173+
;;
174+
esac
175+
176+
echo "Deployment folder name: ${{ steps.branch.outputs.branch_name }}"
177+
echo "Version name for additional deployment (if applicable): ${{ steps.branch.outputs.version_name }}"
178+
179+
- name: Merge ${{ steps.branch.outputs.branch_name }} documentation artifacts into gh-pages
180+
run: |
181+
# List artifacts
182+
ls -la artifacts/*/
183+
184+
# Cleanup old documentation
185+
rm -rf ${{ steps.branch.outputs.branch_name }}
186+
rm -rf server/${{ steps.branch.outputs.branch_name }}
187+
mkdir -p server/${{ steps.branch.outputs.branch_name }}
188+
189+
# Copy all built documentation into dedicated subdirectories
190+
for artifact in artifacts/*; do
191+
if [ -d "$artifact" ]; then
192+
manual_name="$(basename "$artifact")"
193+
mkdir -p "server/${{ steps.branch.outputs.branch_name }}/$manual_name"
194+
cp -r "$artifact/"* "server/${{ steps.branch.outputs.branch_name }}/$manual_name/"
195+
fi
196+
done
197+
198+
# Move pdf files to the root of the branch_name
199+
mv server/${{ steps.branch.outputs.branch_name }}/*/*.pdf server/${{ steps.branch.outputs.branch_name }}/ || true
200+
201+
# If this is the highest stable branch, also deploy to its versioned folder
202+
if [ -n "${{ steps.branch.outputs.version_name }}" ]; then
203+
rm -rf server/${{ steps.branch.outputs.version_name }}
204+
cp -r server/${{ steps.branch.outputs.branch_name }} server/${{ steps.branch.outputs.version_name }}
205+
fi
206+
207+
# Cleanup
208+
find . -type d -empty -delete
209+
rm -rf artifacts
210+
211+
- name: Add various redirects for go.php and user_manual english version
212+
run: |
213+
# Fetch source branches so git checkout origin/... works from the gh-pages checkout
214+
git fetch origin ${{ github.event.repository.default_branch }} ${{ github.ref_name }}
215+
216+
# Generate go.php redirect from main branch
217+
git checkout origin/${{ github.event.repository.default_branch }} -- go.php/index.html
218+
mkdir -p server/${{ steps.branch.outputs.branch_name }}/go.php
219+
mv go.php/index.html server/${{ steps.branch.outputs.branch_name }}/go.php/index.html
220+
221+
# Generate user_manual english redirect
222+
git checkout origin/${{ github.ref_name }} -- user_manual/index.html
223+
mkdir -p server/${{ steps.branch.outputs.branch_name }}/user_manual
224+
mv user_manual/index.html server/${{ steps.branch.outputs.branch_name }}/user_manual/index.html
225+
226+
- name: Commit ${{ steps.branch.outputs.branch_name }} documentation and push to gh-pages
227+
run: |
228+
git config --local user.email "action@github.com"
229+
git config --local user.name "GitHub Action"
230+
git add .
231+
git diff --staged --quiet || git commit -m "chore: deploy documentation for ${{ steps.branch.outputs.branch_name }}"
232+
# Ensure we are up to date with the remote gh-pages branch
233+
git pull --rebase origin gh-pages || true
234+
git push origin gh-pages || echo "Nothing to push (expected if no changes)"
235+
236+
summary:
237+
needs: build
82238
runs-on: ubuntu-latest
239+
if: always()
240+
241+
permissions:
242+
contents: read
243+
244+
name: build-deploy-summary
245+
83246
steps:
84-
- name: Checkout
85-
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
86-
with:
87-
persist-credentials: false
88-
89-
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
90-
with:
91-
python-version: '3.12'
92-
cache: 'pip'
93-
- name: Install pip dependencies
94-
run: pip install -r requirements.txt
95-
- name: Build using Makefile
96-
run: cd admin_manual && make html
97-
- name: Pack the results in local tar file
98-
shell: bash
99-
run: tar czf /tmp/documentation.tar.gz -C admin_manual/_build/html/com .
100-
- name: Upload static documentation
101-
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
102-
with:
103-
name: Administration manual.zip
104-
path: "/tmp/documentation.tar.gz"
247+
# Only check if the build was successful
248+
- name: Summary status
249+
run: if ${{ needs.build.result != 'success' }}; then exit 1; fi

0 commit comments

Comments
 (0)