Skip to content

Commit 962d986

Browse files
search5claude
search5
and
claude
committed
Add version switcher inside Sphinx docs sidebar
- Override rtd theme navigation block with version dropdown - Fetch versions.json dynamically to populate version list - Each version's docs include doc-version meta tag - Root index.html redirects to /latest/ - Workflow generates versions.json from all release tags Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 9427542 commit 962d986

3 files changed

Lines changed: 72 additions & 37 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 27 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -40,56 +40,46 @@ jobs:
4040
for tag in $(git tag --list 'v*' --sort=-version:refname); do
4141
echo "Building docs for $tag"
4242
git checkout "$tag" -- docs/ solr/ 2>/dev/null || continue
43-
version_dir="_site/${tag}"
44-
mkdir -p "$version_dir"
45-
sphinx-build -b html docs "$version_dir" 2>/dev/null || echo " Skipped $tag (build failed)"
43+
mkdir -p "_site/${tag}"
44+
sphinx-build -b html docs "_site/${tag}" 2>/dev/null || echo " Skipped $tag (build failed)"
4645
git checkout master -- docs/ solr/ 2>/dev/null
4746
done
4847
49-
- name: Generate version index page
48+
- name: Generate versions.json
5049
run: |
5150
LATEST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1)
52-
cat > _site/index.html << 'HEADER'
53-
<!DOCTYPE html>
54-
<html>
55-
<head>
56-
<meta charset="utf-8">
57-
<title>solrpy Documentation</title>
58-
<style>
59-
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 700px; margin: 60px auto; padding: 0 20px; color: #333; }
60-
h1 { border-bottom: 2px solid #2980b9; padding-bottom: 10px; }
61-
a { color: #2980b9; text-decoration: none; }
62-
a:hover { text-decoration: underline; }
63-
ul { list-style: none; padding: 0; }
64-
li { padding: 8px 0; border-bottom: 1px solid #eee; }
65-
.latest { font-weight: bold; }
66-
.badge { background: #2980b9; color: #fff; padding: 2px 8px; border-radius: 4px; font-size: 0.8em; margin-left: 8px; }
67-
</style>
68-
</head>
69-
<body>
70-
<h1>solrpy Documentation</h1>
71-
<p><a href="latest/">Latest (master)</a></p>
72-
<h2>Versions</h2>
73-
<ul>
74-
HEADER
75-
51+
echo '[' > _site/versions.json
52+
echo " {\"version\": \"latest\", \"label\": \"latest (master)\", \"path\": \"latest\"}," >> _site/versions.json
53+
first=true
7654
for tag in $(git tag --list 'v*' --sort=-version:refname); do
7755
if [ -d "_site/${tag}" ]; then
78-
badge=""
56+
label="${tag}"
7957
if [ "$tag" = "$LATEST_TAG" ]; then
80-
badge='<span class="badge">latest release</span>'
58+
label="${tag} (stable)"
59+
fi
60+
if [ "$first" = true ]; then
61+
first=false
62+
else
63+
echo "," >> _site/versions.json
8164
fi
82-
echo " <li><a href=\"${tag}/\">${tag}</a>${badge}</li>" >> _site/index.html
65+
printf " {\"version\": \"%s\", \"label\": \"%s\", \"path\": \"%s\"}" "$tag" "$label" "$tag" >> _site/versions.json
8366
fi
8467
done
68+
echo "" >> _site/versions.json
69+
echo ']' >> _site/versions.json
8570
86-
cat >> _site/index.html << 'FOOTER'
87-
</ul>
88-
<hr>
89-
<p><a href="https://github.com/search5/solrpy">GitHub</a> · <a href="https://pypi.org/project/solrpy/">PyPI</a></p>
90-
</body>
71+
- name: Generate root redirect
72+
run: |
73+
cat > _site/index.html << 'EOF'
74+
<!DOCTYPE html>
75+
<html>
76+
<head>
77+
<meta http-equiv="refresh" content="0; url=latest/">
78+
<link rel="canonical" href="latest/">
79+
</head>
80+
<body><a href="latest/">Redirecting to latest documentation...</a></body>
9181
</html>
92-
FOOTER
82+
EOF
9383
9484
- name: Upload artifact
9585
uses: actions/upload-pages-artifact@v3

‎docs/_templates/layout.html‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{% extends "!layout.html" %}
2+
3+
{% block extrahead %}
4+
{{ super() }}
5+
<meta name="doc-version" content="{{ version }}">
6+
{% endblock %}
7+
8+
{% block navigation %}
9+
<div style="padding: 10px 16px; background: #1a242f; border-bottom: 1px solid #37474f;">
10+
<label for="version-select" style="font-weight: bold; display: block; margin-bottom: 6px; color: #cfd8dc; font-size: 0.85em; text-transform: uppercase; letter-spacing: 0.5px;">Version</label>
11+
<select id="version-select" style="width: 100%; padding: 6px; border: 1px solid #455a64; border-radius: 3px; background: #37474f; color: #eceff1; font-size: 0.9em;" onchange="if(this.value) window.location.href=this.value;">
12+
<option value="">Loading...</option>
13+
</select>
14+
</div>
15+
<script>
16+
(function() {
17+
var basePath = '/solrpy';
18+
fetch(basePath + '/versions.json')
19+
.then(function(r) { return r.json(); })
20+
.then(function(versions) {
21+
var sel = document.getElementById('version-select');
22+
sel.innerHTML = '';
23+
var metaTag = document.querySelector('meta[name="doc-version"]');
24+
var currentVer = metaTag ? metaTag.content : '';
25+
versions.forEach(function(v) {
26+
var opt = document.createElement('option');
27+
opt.value = basePath + '/' + v.path + '/';
28+
opt.textContent = v.label;
29+
if (v.version === currentVer) opt.selected = true;
30+
sel.appendChild(opt);
31+
});
32+
})
33+
.catch(function() {
34+
var sel = document.getElementById('version-select');
35+
sel.innerHTML = '<option>versions unavailable</option>';
36+
});
37+
})();
38+
</script>
39+
{{ super() }}
40+
{% endblock %}

‎docs/conf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@
3232

3333
htmlhelp_basename = 'solrpydoc'
3434

35+
# Version meta tag for the version switcher template
36+
html_context = {
37+
'doc_version': version,
38+
}
39+
3540
# -- Intersphinx mapping -----------------------------------------------------
3641

3742
intersphinx_mapping = {

0 commit comments

Comments
 (0)