Skip to content

Commit 10df3fc

Browse files
the-hampelthe-hampel
committed
ci(docs): publish per-branch docs with latest alias on gh-pages
Mimics the triqs core layout within solid_dmft's own gh-pages branch: - unstable & each X.Y.x release deploy into their own subfolder (triqs.github.io/solid_dmft/{unstable,3.3.x,...}/) instead of the root; drop single-commit so sibling version folders survive. - the highest X.Y.x release also deploys to latest/. - new reusable workflow regenerates the root index.html: redirect to latest/ plus an auto-generated version list. - README deep links point at the latest/ docs.
1 parent 755d73d commit 10df3fc

4 files changed

Lines changed: 116 additions & 7 deletions

File tree

‎.github/workflows/build_release.yml‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,41 @@ jobs:
3030

3131
- name: Build solid_dmft
3232
run: |
33-
cmake -S . -B build/
33+
cmake -S . -B build/ -DBuild_Documentation=ON
3434
cmake --build build/ --verbose
3535
3636
- name: Test solid_dmft
3737
run: |
3838
cmake --build build/ --target test
3939
40+
- name: Determine latest release branch
41+
id: latest
42+
run: |
43+
# Highest-version X.Y.x branch on origin is treated as the stable
44+
# release that "latest" points to.
45+
latest=$(git ls-remote --heads origin '[0-9]*.[0-9]*.x' \
46+
| sed 's#.*refs/heads/##' | sort -V | tail -n1)
47+
echo "latest_branch=$latest" >> "$GITHUB_OUTPUT"
48+
echo "Latest release branch: '$latest' (building: '${{ github.ref_name }}')"
49+
50+
- name: Deploy docs for this release 🚀
51+
uses: JamesIves/github-pages-deploy-action@v4
52+
with:
53+
branch: gh-pages
54+
# Each release line gets its own folder (e.g. 3.3.x/). `clean` is scoped
55+
# to this target-folder, so sibling branch folders survive.
56+
folder: build/doc/html/
57+
target-folder: ${{ github.ref_name }}
58+
59+
- name: Deploy docs to latest 🚀
60+
if: steps.latest.outputs.latest_branch == github.ref_name
61+
uses: JamesIves/github-pages-deploy-action@v4
62+
with:
63+
branch: gh-pages
64+
folder: build/doc/html/
65+
target-folder: latest
66+
67+
update-index:
68+
needs: build
69+
uses: ./.github/workflows/update_doc_index.yml
70+

‎.github/workflows/build_unstable_doc.yml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,5 +41,13 @@ jobs:
4141
uses: JamesIves/github-pages-deploy-action@v4
4242
with:
4343
branch: gh-pages
44+
# Publish the unstable docs into their own subfolder so the per-branch
45+
# folders (latest, 3.3.x, ...) coexist on gh-pages. `clean` is scoped to
46+
# this target-folder, so sibling folders survive. Do NOT set
47+
# single-commit here: it would wipe the whole branch (and all siblings).
4448
folder: build/doc/html/
45-
single-commit: true
49+
target-folder: unstable
50+
51+
update-index:
52+
needs: build
53+
uses: ./.github/workflows/update_doc_index.yml

‎.github/workflows/update_doc_index.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: update doc index
2+
3+
# Reusable workflow: regenerates the root index.html on the gh-pages branch so
4+
# that visiting https://triqs.github.io/solid_dmft/ redirects to latest/ and
5+
# lists every published version folder. Called after a docs deploy.
6+
7+
on:
8+
workflow_call:
9+
10+
permissions:
11+
contents: write
12+
13+
jobs:
14+
update-index:
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Checkout gh-pages
19+
uses: actions/checkout@v7
20+
with:
21+
ref: gh-pages
22+
fetch-depth: 0
23+
24+
- name: Generate root index.html
25+
shell: bash
26+
run: |
27+
set -e
28+
# Top-level directories are the version folders (latest, unstable,
29+
# 3.3.x, ...). List them all except "latest" in the navigation list,
30+
# newest first via version sort. Use globbing (not `ls` parsing) so
31+
# folder names are taken verbatim.
32+
shopt -s nullglob
33+
dirs=()
34+
for p in */; do
35+
name="${p%/}"
36+
[ "$name" = "latest" ] && continue
37+
dirs+=("$name")
38+
done
39+
sorted=$(printf '%s\n' "${dirs[@]}" | sort -Vr)
40+
{
41+
echo '<html>'
42+
echo '<head>'
43+
echo ' <meta http-equiv="refresh" content="0; url=latest/">'
44+
echo '</head>'
45+
echo '<body>'
46+
echo ' <ul>'
47+
while IFS= read -r d; do
48+
[ -z "$d" ] && continue
49+
echo " <li><a href=\"$d/\">$d</a></li>"
50+
done <<< "$sorted"
51+
echo ' </ul>'
52+
echo '</body>'
53+
echo '</html>'
54+
} > index.html
55+
cat index.html
56+
57+
- name: Commit and push index
58+
run: |
59+
git config user.name "github-actions[bot]"
60+
git config user.email "github-actions[bot]@users.noreply.github.com"
61+
git add index.html
62+
git diff --quiet --cached && { echo "index unchanged"; exit 0; }
63+
git commit -m "Update root doc index"
64+
# Retry on a concurrent gh-pages write (e.g. parallel doc deploy).
65+
for i in 1 2 3; do
66+
git push && exit 0
67+
echo "push failed, rebasing and retrying ($i)..."
68+
git pull --rebase origin gh-pages
69+
done
70+
git push

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ This program allows to perform DFT+DMFT one-shot and charge self-consistent (CSC
1313
### Documentation & tutorials
1414

1515
To learn how to use solid_dmft, take a look at the [online documentation](https://triqs.github.io/solid_dmft/). There you can find:
16-
* [input / output documentation](https://triqs.github.io/solid_dmft/documentation.html#input-output)
17-
* [reference manual of functions](https://triqs.github.io/solid_dmft/documentation.html#module-reference-manual)
18-
* [code structure](https://triqs.github.io/solid_dmft/documentation.html#code-structure)
19-
* [tutorials](https://triqs.github.io/solid_dmft/tutorials.html)
16+
* [input / output documentation](https://triqs.github.io/solid_dmft/latest/documentation.html#input-output)
17+
* [reference manual of functions](https://triqs.github.io/solid_dmft/latest/documentation.html#module-reference-manual)
18+
* [code structure](https://triqs.github.io/solid_dmft/latest/documentation.html#code-structure)
19+
* [tutorials](https://triqs.github.io/solid_dmft/latest/tutorials.html)
2020

2121
Check also the [solid_dmft publication](https://doi.org/10.21105/joss.04623) in the JOSS journal for more information and further references.
2222

@@ -30,7 +30,7 @@ However, please make sure that you have a valid TRIQS and TRIQS/DFTTools install
3030

3131
A more thorough installation can be performed manually via `cmake`, which will also check if you have a working and matching TRIQS installation.
3232

33-
Please check the [installation page](https://triqs.github.io/solid_dmft/install.html) on the online documentation for more detailed instructions.
33+
Please check the [installation page](https://triqs.github.io/solid_dmft/latest/install.html) on the online documentation for more detailed instructions.
3434

3535
---
3636

0 commit comments

Comments
 (0)