Skip to content

Commit 83a44a5

Browse files
ahmedfgadahmedfgad
committed
Show recent release notes first with expandable history
1 parent a44c29e commit 83a44a5

4 files changed

Lines changed: 768 additions & 554 deletions

File tree

‎docs/source/_static/custom.css‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,80 @@ details.sd-dropdown > summary.sd-summary-title code,
4141
details.sd-dropdown > .sd-summary-title code {
4242
font-weight: 600;
4343
}
44+
45+
/* Release-history controls follow the theme in light and dark mode. */
46+
/* Keep the release-page header compact so the newest notes are in view. */
47+
#release-history > p > img[alt="PYGAD-LOGO"] {
48+
max-width: 12rem;
49+
height: auto;
50+
}
51+
52+
.release-history-navigation {
53+
display: flex;
54+
flex-wrap: wrap;
55+
align-items: center;
56+
gap: 0.75rem;
57+
margin: 1.5rem 0;
58+
}
59+
60+
.release-history-navigation select {
61+
max-width: 100%;
62+
padding: 0.5rem;
63+
border: 1px solid var(--color-brand-primary);
64+
border-radius: 0.35rem;
65+
background: var(--color-background-primary);
66+
color: var(--color-foreground-primary);
67+
font: inherit;
68+
}
69+
70+
.release-history-controls {
71+
display: flex;
72+
flex-wrap: wrap;
73+
gap: 0.75rem;
74+
margin: 2rem 0;
75+
}
76+
77+
.release-history-controls p {
78+
flex-basis: 100%;
79+
margin: 0;
80+
color: var(--color-foreground-secondary);
81+
}
82+
83+
.release-history-controls button {
84+
padding: 0.65rem 1rem;
85+
border: 1px solid var(--color-brand-primary);
86+
border-radius: 0.35rem;
87+
background: var(--color-background-primary);
88+
color: var(--color-brand-content);
89+
font: inherit;
90+
cursor: pointer;
91+
}
92+
93+
.release-history-controls button:hover {
94+
background: var(--color-background-secondary);
95+
}
96+
97+
.release-history-controls button:focus-visible,
98+
.release-history-navigation select:focus-visible {
99+
outline: 2px solid var(--color-brand-primary);
100+
outline-offset: 3px;
101+
}
102+
103+
/* Some theme display rules otherwise override the native hidden attribute. */
104+
#release-history > section[hidden],
105+
.toc-tree li[hidden],
106+
.release-history-controls button[hidden] {
107+
display: none;
108+
}
109+
110+
/* Printed and exported notes always include the complete release history. */
111+
@media print {
112+
#release-history > section[hidden] {
113+
display: block;
114+
}
115+
116+
.release-history-controls,
117+
.release-history-navigation {
118+
display: none;
119+
}
120+
}

‎docs/source/_static/release-history.js‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
// Show recent release notes first, with older notes available on the same page.
2+
// All notes remain in the HTML for documentation search, printing, and readers
3+
// without JavaScript. Existing release links reveal their target automatically.
4+
window.addEventListener("DOMContentLoaded", function () {
5+
var releaseHistory = document.getElementById("release-history");
6+
if (!releaseHistory) {
7+
return;
8+
}
9+
10+
var releaseSections = Array.from(releaseHistory.children).filter(function (element) {
11+
return element.tagName === "SECTION";
12+
});
13+
var releasesPerPage = 10;
14+
if (releaseSections.length <= releasesPerPage) {
15+
return;
16+
}
17+
18+
var visibleReleaseCount = releasesPerPage;
19+
var contentsLinks = Array.from(document.querySelectorAll(".toc-tree a"));
20+
var navigation = document.createElement("div");
21+
navigation.className = "release-history-navigation";
22+
var jumpLabel = document.createElement("label");
23+
jumpLabel.htmlFor = "release-history-version";
24+
jumpLabel.textContent = "Jump to a release";
25+
navigation.appendChild(jumpLabel);
26+
var releaseSelector = document.createElement("select");
27+
releaseSelector.id = "release-history-version";
28+
var placeholder = document.createElement("option");
29+
placeholder.value = "";
30+
placeholder.textContent = "Select a release";
31+
releaseSelector.appendChild(placeholder);
32+
releaseSections.forEach(function (section) {
33+
var option = document.createElement("option");
34+
option.value = section.id;
35+
option.textContent = section.querySelector("h2").firstChild.textContent.trim();
36+
releaseSelector.appendChild(option);
37+
});
38+
navigation.appendChild(releaseSelector);
39+
releaseHistory.insertBefore(navigation, releaseSections[0]);
40+
41+
var controls = document.createElement("div");
42+
controls.className = "release-history-controls";
43+
controls.setAttribute("role", "group");
44+
controls.setAttribute("aria-label", "Older release notes");
45+
46+
var status = document.createElement("p");
47+
status.setAttribute("role", "status");
48+
status.setAttribute("aria-live", "polite");
49+
controls.appendChild(status);
50+
51+
var showMoreButton = document.createElement("button");
52+
showMoreButton.type = "button";
53+
showMoreButton.textContent = "Show 10 more releases";
54+
controls.appendChild(showMoreButton);
55+
56+
var showAllButton = document.createElement("button");
57+
showAllButton.type = "button";
58+
showAllButton.textContent = "Show all releases";
59+
controls.appendChild(showAllButton);
60+
releaseHistory.appendChild(controls);
61+
62+
function updateVisibleReleases() {
63+
releaseSections.forEach(function (section, index) {
64+
section.hidden = index >= visibleReleaseCount;
65+
});
66+
contentsLinks.forEach(function (link) {
67+
var section = document.getElementById(link.hash.slice(1));
68+
var item = link.closest("li");
69+
if (section && releaseSections.indexOf(section) !== -1 && item) {
70+
item.hidden = section.hidden;
71+
}
72+
});
73+
var remainingReleaseCount = releaseSections.length - visibleReleaseCount;
74+
status.textContent = "Showing " + visibleReleaseCount + " of " +
75+
releaseSections.length + " release entries.";
76+
var nextReleaseCount = Math.min(releasesPerPage, remainingReleaseCount);
77+
showMoreButton.textContent = "Show " + nextReleaseCount + " more " +
78+
(nextReleaseCount === 1 ? "release" : "releases");
79+
showMoreButton.hidden = remainingReleaseCount === 0;
80+
showAllButton.hidden = remainingReleaseCount === 0;
81+
}
82+
83+
function showOlderReleases(count) {
84+
var firstNewSection = releaseSections[visibleReleaseCount];
85+
visibleReleaseCount = Math.min(count, releaseSections.length);
86+
updateVisibleReleases();
87+
// Move keyboard focus to the newly revealed notes, rather than leaving
88+
// it on a button that moved below them or disappeared after "Show all".
89+
var heading = firstNewSection.querySelector("h2");
90+
heading.setAttribute("tabindex", "-1");
91+
heading.focus({ preventScroll: true });
92+
heading.scrollIntoView({ block: "start" });
93+
}
94+
95+
function revealLinkedRelease() {
96+
var targetId;
97+
try {
98+
targetId = decodeURIComponent(window.location.hash.slice(1));
99+
} catch (error) {
100+
return;
101+
}
102+
var target = document.getElementById(targetId);
103+
var releaseIndex = releaseSections.findIndex(function (section) {
104+
return target && section.contains(target);
105+
});
106+
if (releaseIndex === -1) {
107+
return;
108+
}
109+
releaseSelector.value = releaseSections[releaseIndex].id;
110+
if (releaseIndex >= visibleReleaseCount) {
111+
visibleReleaseCount = Math.min(releaseSections.length,
112+
Math.ceil((releaseIndex + 1) / releasesPerPage) * releasesPerPage);
113+
updateVisibleReleases();
114+
}
115+
target.scrollIntoView({ block: "start" });
116+
}
117+
118+
showMoreButton.addEventListener("click", function () {
119+
showOlderReleases(visibleReleaseCount + releasesPerPage);
120+
});
121+
showAllButton.addEventListener("click", function () {
122+
showOlderReleases(releaseSections.length);
123+
});
124+
releaseSelector.addEventListener("change", function () {
125+
if (releaseSelector.value) {
126+
var releaseHash = "#" + releaseSelector.value;
127+
window.location.hash = releaseHash;
128+
revealLinkedRelease();
129+
}
130+
});
131+
window.addEventListener("hashchange", revealLinkedRelease);
132+
updateVisibleReleases();
133+
revealLinkedRelease();
134+
});

‎docs/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@
5959
html_title = 'PyGAD'
6060
html_static_path = ['_static']
6161
html_css_files = ['custom.css']
62-
html_js_files = ['scroll-sidebar.js']
62+
html_js_files = ['scroll-sidebar.js', 'release-history.js']
6363

6464
html_theme_options = {
6565
'light_css_variables': {

0 commit comments

Comments
 (0)