Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

docs: reposition version picker in header (#10418)

Isaac Millerc4717b6320eb
diff --git a/docs/scripts/build_docs.py b/docs/scripts/build_docs.py
index d09fefe0d..d10e12734 100644
--- a/docs/scripts/build_docs.py
+++ b/docs/scripts/build_docs.py
@@ -26,7 +26,7 @@ VERSIONED_PATH = re.compile(r"^/(?:current|\d+\.\d+(?:\.\d+(?:(?:a|b|rc)\d+)?)?)
RELEASE_BADGE_VERSION = re.compile(
r'(?s)(<div class=(?:"hp-hero-badge"|hp-hero-badge)>.*?\bDSPy )(\S+)(\s+&mdash;)'
)
-SHARED_HEADER_STYLES = Path(__file__).parent.parent / "versioning" / "header.css"
+SHARED_HEADER_ASSETS = Path(__file__).parent.parent / "versioning"
def release_version(value: str) -> str:
@@ -89,17 +89,25 @@ def remove_source_maps(site: Path) -> dict[str, int]:
return {"before": before, "after": after, "source_maps": len(source_maps)}
-def install_shared_header_styles(site: Path, source: Path = SHARED_HEADER_STYLES) -> None:
+def install_shared_header(site: Path, source: Path = SHARED_HEADER_ASSETS) -> None:
"""Give every renderer and historical snapshot the same header controls."""
- destination = site / "_static" / "dspy-header.css"
- destination.parent.mkdir(parents=True, exist_ok=True)
- destination.write_bytes(source.read_bytes())
+ destination = site / "_static"
+ destination.mkdir(parents=True, exist_ok=True)
+ styles = destination / "dspy-header.css"
+ script = destination / "dspy-header.js"
+ styles.write_bytes((source / "header.css").read_bytes())
+ script.write_bytes((source / "header.js").read_bytes())
for page in site.rglob("*.html"):
- relative = Path(os.path.relpath(destination, page.parent)).as_posix()
- tag = f'<link rel="stylesheet" href="{relative}">'
+ relative_styles = Path(os.path.relpath(styles, page.parent)).as_posix()
+ relative_script = Path(os.path.relpath(script, page.parent)).as_posix()
+ style_tag = f'<link rel="stylesheet" href="{relative_styles}">'
+ script_tag = f'<script src="{relative_script}" defer></script>'
html = page.read_text()
- if tag not in html:
- page.write_text(html.replace("</head>", f"{tag}</head>", 1))
+ if style_tag not in html:
+ html = html.replace("</head>", f"{style_tag}</head>", 1)
+ if script_tag not in html:
+ html = html.replace("</head>", f"{script_tag}</head>", 1)
+ page.write_text(html)
def scope_root_relative_urls(site: Path, identifier: str) -> None:
@@ -224,7 +232,7 @@ def build(
scope_root_relative_urls(output, identifier)
if version:
validate_release_site(output, config, version)
- install_shared_header_styles(output)
+ install_shared_header(output)
optimization = remove_source_maps(output)
if version:
repository = config.parent.parent
diff --git a/docs/versioning/header.css b/docs/versioning/header.css
index 798de20ee..a3be93958 100644
--- a/docs/versioning/header.css
+++ b/docs/versioning/header.css
@@ -1,12 +1,19 @@
/* Shared header treatment for Material release snapshots and Zensical Current. */
+.md-version__alias {
+ display: none;
+}
+
@media screen and (min-width: 60em) {
- .md-version {
+ .md-header__inner > .md-version {
+ flex: 0 0 5.25rem;
position: relative;
+ width: 5.25rem;
height: 2.4rem;
+ margin-right: 0;
margin-left: 0.4rem;
}
- .md-version__current {
+ .md-header__inner > .md-version .md-version__current {
box-sizing: border-box;
min-width: 5.25rem;
height: 1.8rem;
@@ -18,11 +25,11 @@
font-weight: 600;
}
- .md-version__list {
+ .md-header__inner > .md-version .md-version__list {
top: calc(100% - 0.3rem);
- right: auto;
- left: 1.4rem;
- width: 9.5rem;
+ right: 0;
+ left: auto;
+ width: 8rem;
max-height: 19rem;
margin-right: 0;
margin-left: 0;
@@ -64,11 +71,6 @@
color: var(--md-accent-fg-color);
}
- /* Minor aliases remain redirects, but patches are the selectable versions. */
- .md-version__alias {
- display: none;
- }
-
/* Match the wider search field used by the historical Material header. */
.md-search {
width: 13rem;
@@ -86,4 +88,9 @@
.md-search__button::after {
display: none;
}
+
+ .md-header__source {
+ width: 8.7rem;
+ margin-left: 0;
+ }
}
diff --git a/docs/versioning/header.js b/docs/versioning/header.js
new file mode 100644
index 000000000..ff5ab3838
--- /dev/null
+++ b/docs/versioning/header.js
@@ -0,0 +1,26 @@
+document.addEventListener("DOMContentLoaded", () => {
+ const desktop = window.matchMedia("(min-width: 60em)");
+
+ function placeVersionPicker() {
+ const picker = document.querySelector(".md-version");
+ const search = document.querySelector(".md-search");
+ const title = document.querySelector(".md-header__topic");
+ if (!picker || !search || !title) return false;
+
+ if (desktop.matches) {
+ search.after(picker);
+ } else {
+ title.append(picker);
+ }
+ return true;
+ }
+
+ if (!placeVersionPicker()) {
+ const observer = new MutationObserver(() => {
+ if (placeVersionPicker()) observer.disconnect();
+ });
+ observer.observe(document.body, { childList: true, subtree: true });
+ }
+
+ desktop.addEventListener("change", placeVersionPicker);
+});
diff --git a/tests/docs/test_versioned_docs.py b/tests/docs/test_versioned_docs.py
index b23ab1d77..41fcac62d 100644
--- a/tests/docs/test_versioned_docs.py
+++ b/tests/docs/test_versioned_docs.py
@@ -6,6 +6,7 @@ import subprocess
import pytest
from docs.scripts.build_docs import (
+ install_shared_header,
patched_config,
release_version,
remove_source_maps,
@@ -93,6 +94,22 @@ def test_production_build_removes_source_maps(tmp_path):
assert "sourceMappingURL" not in (assets / "app.js").read_text()
+def test_shared_header_assets_are_installed_on_nested_pages(tmp_path):
+ site = make_site(tmp_path, "Home")
+
+ install_shared_header(site)
+ install_shared_header(site)
+
+ assert (site / "_static" / "dspy-header.css").is_file()
+ assert (site / "_static" / "dspy-header.js").is_file()
+ home = (site / "index.html").read_text()
+ nested = (site / "guide" / "index.html").read_text()
+ assert home.count('href="_static/dspy-header.css"') == 1
+ assert home.count('src="_static/dspy-header.js"') == 1
+ assert nested.count('href="../_static/dspy-header.css"') == 1
+ assert nested.count('src="../_static/dspy-header.js"') == 1
+
+
def test_root_relative_links_stay_inside_the_selected_version(tmp_path):
site = tmp_path / "site"
site.mkdir()