DSPy: The framework for programming—not prompting—language models
Python
Fix broken notebook links in docs (#10513)
Thomas Hjelde Thoresenda1736e21ffd
diff --git a/docs/scripts/zensical_build.py b/docs/scripts/zensical_build.pyindex 343efec31..0bb0b4b39 100644--- a/docs/scripts/zensical_build.py+++ b/docs/scripts/zensical_build.py@@ -113,13 +113,34 @@ def write_redirects(site: Path, redirects: dict[str, str]) -> None:destination.write_text(redirect_document(relative))+NOTEBOOK_LINK = re.compile(r"\]\((?P<target>[^)\s#]+)\.ipynb(?P<suffix>#[^)\s]*)?\)")+++def rewrite_notebook_links(docs: Path, notebooks: set[Path]) -> None:+ """Point Markdown links at converted notebooks to their generated pages, as mkdocs-jupyter did."""++ for page in docs.rglob("*.md"):+ text = page.read_text()++ def replace(match: re.Match[str], page: Path = page) -> str:+ target = match["target"]+ if (page.parent / f"{target}.ipynb").resolve() not in notebooks:+ return match[0]+ return f"]({target}.md{match['suffix'] or ''})"++ rewritten = NOTEBOOK_LINK.sub(replace, text)+ if rewritten != text:+ page.write_text(rewritten)++def convert_notebooks(docs: Path) -> set[str]:from nbconvert import MarkdownExporterexporter = MarkdownExporter()routes = set()- for notebook in docs.rglob("*.ipynb"):- relative = notebook.relative_to(docs).with_suffix(".md").as_posix()+ notebooks = {notebook.resolve() for notebook in docs.rglob("*.ipynb")}+ for notebook in notebooks:+ relative = notebook.relative_to(docs.resolve()).with_suffix(".md").as_posix()routes.add(route_for_source(relative).lstrip("/") + "index.html")body, resources = exporter.from_filename(str(notebook), resources={"output_files_dir": f"{notebook.stem}_files"}@@ -130,6 +151,7 @@ def convert_notebooks(docs: Path) -> set[str]:output.parent.mkdir(parents=True, exist_ok=True)output.write_bytes(content)notebook.unlink()+ rewrite_notebook_links(docs, notebooks)for source in docs.rglob("*.py"):relative = source.relative_to(docs).with_suffix(".md").as_posix()routes.add(route_for_source(relative).lstrip("/") + "index.html")@@ -287,6 +309,9 @@ def social_cards(site: Path, site_url: str, titles: dict[str, str], logo: Path)page.write_text(html.replace("</head>", f"{tags}</head>", 1))+HREF = re.compile(r"""href=["']?([^"'\s>]+)""")++def validate_output(site: Path, notebook_routes: set[str], redirects: dict[str, str]) -> None:"""Fail the build when an existing documentation feature has no output."""required = ("index.html", "api/index.html", "search.json", "llms.txt", "sitemap.xml", "sitemap.xml.gz")@@ -310,6 +335,15 @@ def validate_output(site: Path, notebook_routes: set[str], redirects: dict[str,if not any(cards.glob("*.png")) or 'property="og:image"' not in home:raise RuntimeError("social cards or Open Graph metadata were not generated")+ notebook_links = [+ f"{page.relative_to(site).as_posix()} -> {href}"+ for page in site.rglob("*.html")+ for href in HREF.findall(page.read_text())+ if ":" not in href and not href.startswith("//") and re.split(r"[?#]", href)[0].endswith(".ipynb")+ ]+ if notebook_links:+ raise RuntimeError(f"pages link to notebook sources instead of rendered pages: {', '.join(notebook_links)}")+def build_zensical_site(*,