Skip to content

Commit cadebd8

Browse files
paulgessingerJustusRudolph
paulgessinger
authored and
JustusRudolph
committed
ci: Docs build PR banner + prepped for version banner (acts-project#4943)
This PR introduces sending built documentation packages for the main branch and tags over to a receiving repository, which will be configured to build a versioned documentation page from them.
1 parent 7eab220 commit cadebd8

File tree

11 files changed

+516
-61
lines changed

11 files changed

+516
-61
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 43 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -13,51 +13,8 @@ concurrency:
1313
cancel-in-progress: true
1414

1515
jobs:
16-
docs-old:
17-
runs-on: ubuntu-latest
18-
env:
19-
DOXYGEN_WARN_AS_ERROR: FAIL_ON_WARNINGS
20-
DOXYGEN_VERSION: "1.15.0"
21-
DOXYGEN_HASH: "0ec2e5b2c3cd82b7106d19cb42d8466450730b8cb7a9e85af712be38bf4523a1"
22-
steps:
23-
- uses: actions/checkout@v6
24-
25-
- name: Install doxygen
26-
run: |
27-
curl -SL https://acts.web.cern.ch/ci/doxygen/doxygen-${{ env.DOXYGEN_VERSION }}.linux.bin.tar.gz -o doxygen-${{ env.DOXYGEN_VERSION }}.linux.bin.tar.gz
28-
echo "${{ env.DOXYGEN_HASH }} doxygen-${{ env.DOXYGEN_VERSION }}.linux.bin.tar.gz" | sha256sum -c -
29-
tar xf doxygen-${{ env.DOXYGEN_VERSION }}.linux.bin.tar.gz
30-
mv doxygen-${{ env.DOXYGEN_VERSION }}/bin/doxygen /usr/local/bin/doxygen
31-
32-
- name: Install dependencies
33-
run: >
34-
pip3 install --upgrade pip
35-
&& pip install -r docs/old/requirements.txt
36-
37-
- name: Build documentation
38-
run: >
39-
cd docs/old
40-
&& sphinx-build
41-
-b html
42-
-d _build/doctrees/
43-
-j auto
44-
-W
45-
--keep-going
46-
-t run_doxygen
47-
-t lazy_autodoc
48-
-t white_papers
49-
-b linkcheck
50-
. _build/html/
51-
52-
53-
- uses: actions/upload-artifact@v6
54-
with:
55-
name: acts-docs-old
56-
path: docs/old/_build/html/
57-
5816
docs:
5917
runs-on: ubuntu-latest
60-
# container: ghcr.io/acts-project/ubuntu2404:83
6118
env:
6219
DOXYGEN_WARN_AS_ERROR: FAIL_ON_WARNINGS
6320
DOXYGEN_VERSION: "1.15.0"
@@ -85,11 +42,53 @@ jobs:
8542
run: >
8643
cmake --build build --target docs
8744
45+
- name: Generate PR metadata
46+
if: github.event_name == 'pull_request'
47+
env:
48+
PR_NUMBER: ${{ github.event.pull_request.number }}
49+
PR_BRANCH: ${{ github.head_ref }}
50+
PR_TITLE: ${{ github.event.pull_request.title }}
51+
PR_URL: ${{ github.event.pull_request.html_url }}
52+
run: |
53+
jq -n \
54+
--arg pr "$PR_NUMBER" \
55+
--arg branch "$PR_BRANCH" \
56+
--arg title "$PR_TITLE" \
57+
--arg url "$PR_URL" \
58+
'{pr: ($pr | tonumber), branch: $branch, title: $title, url: $url}' \
59+
> build/docs/html/pr.json
60+
echo "Created pr.json for PR #$PR_NUMBER"
61+
cat build/docs/html/pr.json
62+
8863
- uses: actions/upload-artifact@v6
8964
id: artifact-upload-step
9065
with:
9166
name: acts-docs
9267
path: build/docs/html
9368

9469
- name: Documentation display
95-
run: echo 'https://acts-herald.app.cern.ch/view/${{ github.repository }}/${{ steps.artifact-upload-step.outputs.artifact-id }}/index.html'
70+
run: |
71+
base_link='https://acts-herald.app.cern.ch/view/${{ github.repository }}/${{ steps.artifact-upload-step.outputs.artifact-id }}'
72+
link="$base_link/index.html"
73+
echo "📚 Docs preview available at: $link"
74+
echo "**📚 Documentation preview available [here]($link)**" >> $GITHUB_STEP_SUMMARY
75+
76+
# prime cache
77+
(curl -L -m1 "$link" "$base_link/pr.json" > /dev/null 2>&1) || true
78+
79+
- name: Repository Dispatch
80+
# Dispatch only if on a tag or on the main branch
81+
if: >-
82+
${{
83+
github.event_name == 'push' &&
84+
(
85+
github.ref_type == 'tag' ||
86+
(github.ref_type == 'branch' && github.ref_name == 'main')
87+
)
88+
}}
89+
uses: peter-evans/repository-dispatch@v4
90+
with:
91+
token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
92+
repository: acts-project/acts-project.github.io
93+
event-type: deploy_docs
94+
client-payload: ${{ format('{{"source_repo":{0},"run_id":{1},"artifact_id":{2},"ref":{3},"ref_type":{4},"ref_name":{5},"sha":{6}}}', toJson(github.repository), toJson(github.run_id), toJson(steps.artifact-upload-step.outputs.artifact-id), toJson(github.ref), toJson(github.ref_type), toJson(github.ref_name), toJson(github.sha)) }}

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ repos:
3939
"-I", "./CI/codespell_ignore.txt",
4040
"-w"
4141
]
42-
exclude: ^CI/.*$
42+
exclude: ^CI/.*|docs/tex-mml-chtml.js$
4343

4444
- repo: local
4545
hooks:

‎CI/check_unused_files.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,8 @@ def main():
6767
"todo.md",
6868
"bugs.md",
6969
"deprecated.md",
70+
"acts-version-manager.js",
71+
"tex-mml-chtml.js",
7072
)
7173

7274
suffix_header = (

‎docs/Doxyfile.in‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1162,7 +1162,8 @@ HTML_STYLESHEET =
11621162

11631163
HTML_EXTRA_STYLESHEET = @AWESOME_CSS_DIR@/doxygen-awesome.css \
11641164
@AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only.css \
1165-
@AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only-darkmode-toggle.css
1165+
@AWESOME_CSS_DIR@/doxygen-awesome-sidebar-only-darkmode-toggle.css \
1166+
@CMAKE_CURRENT_SOURCE_DIR@/custom.css
11661167

11671168
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
11681169
# other source files which should be copied to the HTML output directory. Note
@@ -1174,7 +1175,10 @@ HTML_EXTRA_STYLESHEET = @AWESOME_CSS_DIR@/doxygen-awesome.css \
11741175

11751176
HTML_EXTRA_FILES = @AWESOME_CSS_DIR@/doxygen-awesome-darkmode-toggle.js \
11761177
@AWESOME_CSS_DIR@/doxygen-awesome-paragraph-link.js \
1177-
@AWESOME_CSS_DIR@/doxygen-awesome-interactive-toc.js
1178+
@AWESOME_CSS_DIR@/doxygen-awesome-interactive-toc.js \
1179+
@CMAKE_CURRENT_SOURCE_DIR@/tex-mml-chtml.js \
1180+
@CMAKE_CURRENT_SOURCE_DIR@/acts-version-manager.js \
1181+
@CMAKE_CURRENT_SOURCE_DIR@/acts-version-manager.css
11781182

11791183

11801184
HTML_COLORSTYLE = LIGHT

‎docs/acts-version-manager.css‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
/**
2+
* ACTS Version Manager Styles
3+
*
4+
* Styling for PR build banner and version selector.
5+
* Compatible with doxygen-awesome-css theme and dark mode.
6+
*/
7+
8+
/* ========================================================================
9+
PR Build Banner
10+
======================================================================== */
11+
12+
#acts-pr-banner {
13+
background: var(--primary-color, #3f51b5);
14+
color: white;
15+
padding: 12px 20px;
16+
text-align: center;
17+
border-bottom: 1px solid rgba(0, 0, 0, 0.1);
18+
font-size: 14px;
19+
line-height: 1.6;
20+
}
21+
22+
#acts-pr-banner strong {
23+
font-weight: 600;
24+
}
25+
26+
#acts-pr-banner code {
27+
background: rgba(255, 255, 255, 0.2);
28+
padding: 2px 6px;
29+
border-radius: 3px;
30+
font-family: monospace;
31+
font-size: 13px;
32+
}
33+
34+
#acts-pr-banner a {
35+
color: white;
36+
text-decoration: underline;
37+
font-weight: 500;
38+
}
39+
40+
#acts-pr-banner a:hover {
41+
opacity: 0.8;
42+
}
43+
44+
/* Dark mode compatibility for PR banner */
45+
html.dark-mode #acts-pr-banner {
46+
background: #2c3e50;
47+
border-bottom-color: rgba(255, 255, 255, 0.1);
48+
}
49+
50+
html.dark-mode #acts-pr-banner code {
51+
background: rgba(255, 255, 255, 0.15);
52+
}
53+
54+
/* ========================================================================
55+
Version Selector Container
56+
======================================================================== */
57+
58+
#acts-version-selector {
59+
padding: 12px 16px;
60+
border-bottom: 1px solid var(--separator-color);
61+
background: var(--side-nav-background);
62+
position: sticky;
63+
top: 0;
64+
z-index: 200;
65+
/* Prevent layout shift during load */
66+
min-height: 40px;
67+
}
68+
69+
/* Version dropdown styling */
70+
#acts-version-selector select,
71+
#acts-version-selector .version-dropdown {
72+
width: 100%;
73+
padding: 8px;
74+
border: 1px solid var(--separator-color);
75+
border-radius: 4px;
76+
background: var(--page-background-color);
77+
color: var(--page-foreground-color);
78+
font-size: 13px;
79+
cursor: pointer;
80+
transition: border-color 0.2s ease;
81+
}
82+
83+
#acts-version-selector select:hover,
84+
#acts-version-selector .version-dropdown:hover {
85+
border-color: var(--primary-color);
86+
}
87+
88+
#acts-version-selector select:focus,
89+
#acts-version-selector .version-dropdown:focus {
90+
outline: none;
91+
border-color: var(--primary-color);
92+
box-shadow: 0 0 0 2px rgba(63, 81, 181, 0.2);
93+
}
94+
95+
/* Version selector label (if used by external JS) */
96+
#acts-version-selector label {
97+
display: block;
98+
margin-bottom: 6px;
99+
font-size: 12px;
100+
font-weight: 600;
101+
color: var(--page-foreground-color);
102+
opacity: 0.8;
103+
}
104+
105+
/* ========================================================================
106+
Minimal Fallback Selector
107+
======================================================================== */
108+
109+
#acts-version-selector.minimal {
110+
display: flex;
111+
align-items: center;
112+
justify-content: center;
113+
min-height: 44px;
114+
}
115+
116+
#acts-version-selector.minimal a {
117+
display: inline-block;
118+
color: var(--primary-color);
119+
text-decoration: none;
120+
font-size: 13px;
121+
padding: 6px 12px;
122+
border-radius: 4px;
123+
transition: background-color 0.2s ease;
124+
}
125+
126+
#acts-version-selector.minimal a:hover {
127+
text-decoration: underline;
128+
background: rgba(0, 0, 0, 0.05);
129+
}
130+
131+
html.dark-mode #acts-version-selector.minimal a:hover {
132+
background: rgba(255, 255, 255, 0.05);
133+
}
134+
135+
/* ========================================================================
136+
Responsive Design
137+
======================================================================== */
138+
139+
@media screen and (max-width: 767px) {
140+
#acts-pr-banner {
141+
padding: 10px 15px;
142+
font-size: 13px;
143+
}
144+
145+
#acts-version-selector {
146+
padding: 10px 12px;
147+
}
148+
149+
#acts-version-selector select,
150+
#acts-version-selector .version-dropdown {
151+
font-size: 12px;
152+
}
153+
}
154+
155+
/* ========================================================================
156+
Loading State (Optional - for future enhancement)
157+
======================================================================== */
158+
159+
#acts-version-selector.loading {
160+
opacity: 0.6;
161+
pointer-events: none;
162+
}
163+
164+
#acts-version-selector.loading::after {
165+
content: "Loading...";
166+
display: block;
167+
text-align: center;
168+
font-size: 12px;
169+
color: var(--page-foreground-color);
170+
opacity: 0.6;
171+
}

0 commit comments

Comments
 (0)