Skip to content

Commit 6676bc5

Browse files
AAmbujAAmbuj
committed
Docs(sphinx): configure GitHub Pages
added DOCS_BASE_URL-based GitHub Pages URL configuration include version flyout CSS and JS assets in Sphinx output
1 parent b83b645 commit 6676bc5

5 files changed

Lines changed: 435 additions & 1 deletion

File tree

‎.github/workflows/deploy_docs.yml‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# *******************************************************************************
2+
# Copyright (c) 2026 Contributors to the Eclipse Foundation
3+
#
4+
# See the NOTICE file(s) distributed with this work for additional
5+
# information regarding copyright ownership.
6+
#
7+
# This program and the accompanying materials are made available under the
8+
# terms of the Apache License Version 2.0 which is available at
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# SPDX-License-Identifier: Apache-2.0
12+
# *******************************************************************************
13+
14+
# Workflow to build and deploy Sphinx documentation to GitHub Pages with versioning
15+
name: Deploy Documentation to GitHub Pages
16+
17+
on:
18+
push:
19+
branches: [main]
20+
tags: ['v*']
21+
pull_request:
22+
branches: [main]
23+
paths:
24+
- 'docs/**'
25+
- '.github/workflows/deploy_docs.yml'
26+
workflow_dispatch:
27+
28+
permissions:
29+
contents: read
30+
pages: write
31+
id-token: write
32+
33+
concurrency:
34+
group: "pages"
35+
cancel-in-progress: true
36+
37+
env:
38+
ANDROID_HOME: ""
39+
ANDROID_SDK_ROOT: ""
40+
41+
jobs:
42+
build-docs:
43+
runs-on: ubuntu-latest
44+
steps:
45+
- name: Checkout repository
46+
uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
47+
48+
- name: Set up Bazel
49+
uses: bazel-contrib/setup-bazel@0.14.0
50+
with:
51+
bazelisk-cache: true
52+
disk-cache: ${{ github.workflow }}
53+
repository-cache: true
54+
55+
- name: Determine version
56+
id: version
57+
run: |
58+
if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
59+
VERSION="${GITHUB_REF#refs/tags/}"
60+
echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
61+
echo "is_tag=true" >> "$GITHUB_OUTPUT"
62+
echo "should_deploy=true" >> "$GITHUB_OUTPUT"
63+
elif [[ "${GITHUB_REF}" == refs/heads/main ]]; then
64+
echo "version=latest" >> "$GITHUB_OUTPUT"
65+
echo "is_tag=false" >> "$GITHUB_OUTPUT"
66+
echo "should_deploy=true" >> "$GITHUB_OUTPUT"
67+
else
68+
# Feature branch or PR - deploy to preview/<branch-name>
69+
BRANCH_NAME="${GITHUB_REF#refs/heads/}"
70+
BRANCH_NAME="${BRANCH_NAME//\//-}"
71+
echo "version=preview/${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
72+
echo "is_tag=false" >> "$GITHUB_OUTPUT"
73+
echo "should_deploy=true" >> "$GITHUB_OUTPUT"
74+
fi
75+
76+
- name: Build Sphinx documentation
77+
env:
78+
DOCS_BASE_URL: "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
79+
DOCS_VERSION: ${{ steps.version.outputs.version }}
80+
run: |
81+
bazel build //docs/sphinx:sphinx_doc
82+
83+
- name: Prepare documentation output
84+
run: |
85+
mkdir -p docs_output
86+
cp -r bazel-bin/docs/sphinx/sphinx_doc/html/* docs_output/ || \
87+
cp -r bazel-out/k8-fastbuild/bin/docs/sphinx/sphinx_doc/html/* docs_output/ || true
88+
# Fix read-only permissions from Bazel output
89+
chmod -R u+w docs_output/
90+
# Prevent Jekyll from ignoring _static directories
91+
touch docs_output/.nojekyll
92+
# Inject version flyout CSS and JS into all HTML files
93+
# Use shared path so all versions use the same files
94+
REPO_NAME="${{ github.event.repository.name }}"
95+
CSS_TAG="<link rel=\"stylesheet\" type=\"text/css\" href=\"/${REPO_NAME}/_shared/css/version_flyout.css\" />"
96+
JS_TAG="<script src=\"/${REPO_NAME}/_shared/js/version_flyout.js\"></script>"
97+
find docs_output -name '*.html' -exec sed -i \
98+
"s|</head>|${CSS_TAG}\n</head>|" {} +
99+
find docs_output -name '*.html' -exec sed -i \
100+
"s|</body>|${JS_TAG}\n</body>|" {} +
101+
102+
- name: Verify build output
103+
run: |
104+
if [ ! -f docs_output/index.html ]; then
105+
echo "::error::Documentation build failed - no index.html found"
106+
exit 1
107+
fi
108+
echo "Documentation built successfully"
109+
echo "Files generated:"
110+
find docs_output -type f | head -20
111+
112+
- name: Restore previous publish tree
113+
if: github.event_name != 'pull_request'
114+
uses: actions/cache/restore@v4
115+
with:
116+
path: publish
117+
key: docs-publish-${{ github.run_id }}
118+
restore-keys: docs-publish-
119+
120+
- name: Assemble publish tree
121+
if: github.event_name != 'pull_request'
122+
run: |
123+
VERSION="${{ steps.version.outputs.version }}"
124+
IS_TAG="${{ steps.version.outputs.is_tag }}"
125+
REPO_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
126+
127+
mkdir -p publish
128+
129+
rm -rf "publish/${VERSION}"
130+
mkdir -p "publish/${VERSION}"
131+
cp -a docs_output/. "publish/${VERSION}/"
132+
133+
if [[ "${IS_TAG}" == "true" ]]; then
134+
rm -rf publish/stable
135+
cp -a docs_output/. publish/stable/
136+
fi
137+
138+
mkdir -p publish/_shared/css publish/_shared/js
139+
cp docs/sphinx/_static/css/version_flyout.css publish/_shared/css/
140+
cp docs/sphinx/_static/js/version_flyout.js publish/_shared/js/
141+
142+
cp docs/sphinx/_gh_pages/index.html publish/index.html
143+
touch publish/.nojekyll
144+
145+
echo "[" > publish/switcher.json
146+
echo " {\"name\": \"latest\", \"version\": \"latest\", \"url\": \"${REPO_URL}/latest/\"}," >> publish/switcher.json
147+
148+
if [ -d "publish/stable" ]; then
149+
echo " {\"name\": \"stable\", \"version\": \"stable\", \"url\": \"${REPO_URL}/stable/\", \"preferred\": true}," >> publish/switcher.json
150+
fi
151+
152+
for dir in $(find publish -maxdepth 1 -mindepth 1 -type d -name "v*" | sort -rV); do
153+
ver=$(basename "$dir")
154+
echo " {\"name\": \"${ver}\", \"version\": \"${ver}\", \"url\": \"${REPO_URL}/${ver}/\"}," >> publish/switcher.json
155+
done
156+
157+
sed -i '$ s/,$//' publish/switcher.json
158+
echo "]" >> publish/switcher.json
159+
160+
- name: Save publish tree to cache
161+
if: github.event_name != 'pull_request'
162+
uses: actions/cache/save@v4
163+
with:
164+
path: publish
165+
key: docs-publish-${{ github.run_id }}
166+
167+
- name: Setup Pages
168+
if: github.event_name != 'pull_request'
169+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
170+
171+
- name: Upload Pages artifact
172+
if: github.event_name != 'pull_request'
173+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
174+
with:
175+
path: publish
176+
177+
- name: Print preview URL
178+
if: github.event_name != 'pull_request'
179+
run: |
180+
REPO_URL="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
181+
echo "::notice::Documentation deployed to: ${REPO_URL}/${{ steps.version.outputs.version }}/"
182+
183+
deploy-pages:
184+
needs: build-docs
185+
if: github.event_name != 'pull_request'
186+
runs-on: ubuntu-latest
187+
environment:
188+
name: github-pages
189+
url: ${{ steps.deployment.outputs.page_url }}
190+
steps:
191+
- name: Deploy to GitHub Pages
192+
id: deployment
193+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

‎docs/sphinx/_gh_pages/index.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<title>Redirecting to latest documentation...</title>
6+
<meta http-equiv="refresh" content="0; url=latest/">
7+
<link rel="canonical" href="latest/">
8+
</head>
9+
<body>
10+
<p>Redirecting to <a href="latest/">latest documentation</a>...</p>
11+
</body>
12+
</html>

‎docs/sphinx/_static/css/version_flyout.css‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
/* RTD-style version flyout panel */
2+
.version-flyout {
3+
position: fixed;
4+
bottom: 0;
5+
right: 20px;
6+
z-index: 9999;
7+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
8+
font-size: 14px;
9+
}
10+
11+
.version-flyout__toggle {
12+
display: flex;
13+
align-items: center;
14+
gap: 8px;
15+
padding: 8px 16px;
16+
background: #1f1f2e;
17+
color: #fff;
18+
border: none;
19+
border-radius: 6px 6px 0 0;
20+
cursor: pointer;
21+
font-size: 14px;
22+
font-weight: 500;
23+
}
24+
25+
.version-flyout__toggle:hover {
26+
background: #2a2a3d;
27+
}
28+
29+
.version-flyout__toggle .flyout-icon {
30+
font-size: 16px;
31+
}
32+
33+
.version-flyout__toggle .flyout-current {
34+
color: #27ae60;
35+
font-weight: bold;
36+
}
37+
38+
.version-flyout__toggle .flyout-arrow {
39+
margin-left: auto;
40+
transition: transform 0.2s;
41+
}
42+
43+
.version-flyout__toggle.active .flyout-arrow {
44+
transform: rotate(180deg);
45+
}
46+
47+
.version-flyout__panel {
48+
display: none;
49+
background: #1f1f2e;
50+
color: #ccc;
51+
padding: 16px;
52+
border-radius: 6px 6px 0 0;
53+
min-width: 260px;
54+
box-shadow: 0 -4px 16px rgba(0, 0, 0, 0.3);
55+
}
56+
57+
.version-flyout__panel.open {
58+
display: block;
59+
}
60+
61+
.version-flyout__panel h4 {
62+
color: #fff;
63+
margin: 0 0 8px 0;
64+
font-size: 13px;
65+
text-transform: uppercase;
66+
letter-spacing: 0.5px;
67+
}
68+
69+
.version-flyout__panel .flyout-section {
70+
margin-bottom: 12px;
71+
}
72+
73+
.version-flyout__panel .flyout-versions {
74+
display: flex;
75+
flex-wrap: wrap;
76+
gap: 6px;
77+
}
78+
79+
.version-flyout__panel .flyout-versions a {
80+
color: #55b4d4;
81+
text-decoration: none;
82+
padding: 2px 8px;
83+
border-radius: 3px;
84+
font-size: 13px;
85+
}
86+
87+
.version-flyout__panel .flyout-versions a:hover {
88+
background: rgba(255, 255, 255, 0.1);
89+
color: #7dd3fc;
90+
}
91+
92+
.version-flyout__panel .flyout-versions a.active {
93+
color: #27ae60;
94+
font-weight: bold;
95+
}
96+
97+
.version-flyout__panel .flyout-links {
98+
border-top: 1px solid #333;
99+
padding-top: 10px;
100+
margin-top: 10px;
101+
}
102+
103+
.version-flyout__panel .flyout-links a {
104+
display: inline-block;
105+
color: #55b4d4;
106+
text-decoration: none;
107+
margin-right: 12px;
108+
font-size: 13px;
109+
}
110+
111+
.version-flyout__panel .flyout-links a:hover {
112+
color: #7dd3fc;
113+
}
114+
115+
.version-flyout__footer {
116+
font-size: 11px;
117+
color: #888;
118+
margin-top: 10px;
119+
text-align: center;
120+
}
121+
122+
.version-flyout__footer a {
123+
color: #55b4d4;
124+
text-decoration: none;
125+
}

0 commit comments

Comments
 (0)