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.pyindex 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+—)')-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.parentdiff --git a/docs/versioning/header.css b/docs/versioning/header.cssindex 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.jsnew file mode 100644index 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.pyindex b23ab1d77..41fcac62d 100644--- a/tests/docs/test_versioned_docs.py+++ b/tests/docs/test_versioned_docs.py@@ -6,6 +6,7 @@ import subprocessimport pytestfrom 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()