DSPy: The framework for programming—not prompting—language models
Python
docs: migrate Current to native Zensical (#10316)
Isaac Miller4b60eb4477e9
diff --git a/.github/workflows/docs-push.yml b/.github/workflows/docs-push.ymlindex 8cd68a874..ff6420ef0 100644--- a/.github/workflows/docs-push.yml+++ b/.github/workflows/docs-push.yml@@ -31,9 +31,10 @@ jobs:persist-credentials: false- name: Install dependencies and buildrun: |- cd docs- pip install -r requirements.txt- python scripts/build_docs.py current+ pip install -r docs/requirements.txt -e .+ python docs/scripts/build_docs.py current \+ --config docs/mkdocs.yml \+ --output docs/sitedetect-versioned-deployment:if: github.event_name == 'push' && github.repository == 'stanfordnlp/dspy'@@ -133,9 +134,7 @@ jobs:cache: "pip"cache-dependency-path: docs/requirements.txt- name: Install documentation dependencies- run: |- grep -v 'github.com/stanfordnlp/dspy' docs/requirements.txt > "$RUNNER_TEMP/docs-requirements.txt"- python -m pip install -r "$RUNNER_TEMP/docs-requirements.txt" -e .+ run: python -m pip install -r docs/requirements.txt -e .- name: Build Current documentationrun: |python docs/scripts/build_docs.py current \diff --git a/docs/build.yml b/docs/build.ymlnew file mode 100644index 000000000..831107612--- /dev/null+++ b/docs/build.yml@@ -0,0 +1,24 @@+llms:+ markdown_description: >+ DSPy is the framework for programming—rather than prompting—language models.+ DSPy unifies techniques for prompting, fine-tuning, reasoning, tool use, and evaluation of LMs.+ It provides a systematic approach to building AI applications through composable modules,+ optimization techniques, and evaluation frameworks.+ sections:+ Get Started:+ - index.md: DSPy overview and quick start guide+ Getting Started:+ - getting-started/**.md+ Diving Deeper:+ - diving-deeper/**.md+ Tutorials - Docs:+ - tutorials/**.md+ Tutorials - Notebooks:+ - tutorials/**.ipynb+ Community:+ - community/**.md+ FAQ:+ - faqs.md: Common questions on DSPy usage, comparisons, optimization, and debugging+ - cheatsheet.md: DSPy cheatsheet for quick reference+ API Reference:+ - api/**.mddiff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.cssindex 4be8b8949..081978c41 100644--- a/docs/docs/stylesheets/extra.css+++ b/docs/docs/stylesheets/extra.css@@ -34,6 +34,11 @@margin-top: 2rem;}+/* Keep help and project links together at the right edge of the tabs row. */+.md-tabs__item:nth-last-child(2) {+ margin-left: auto;+}+/* Responsive adjustments */@media screen and (min-width: 76.25em) {.md-logo {@@ -44,6 +49,13 @@}}+@media screen and (min-width: 60em) {+ /* Zensical's search surface sits two pixels above Material's input. */+ .md-header__inner > .md-version {+ padding-top: 0.15rem !important;+ }+}+/* Dark mode specific adjustments */[data-md-color-scheme="slate"] .md-logo img {filter: brightness(0.9);diff --git a/docs/hooks/fetch_stats.py b/docs/hooks/fetch_stats.pyindex d28d59956..67432fdf2 100644--- a/docs/hooks/fetch_stats.py+++ b/docs/hooks/fetch_stats.py@@ -6,14 +6,12 @@ Falls back to cached (or hardcoded) values on any API failure."""import json-import os+import loggingimport reimport time-import loggingfrom datetime import datetime, timedeltafrom pathlib import Pathfrom urllib.request import Request, urlopen-from urllib.error import URLErrorlog = logging.getLogger("mkdocs.hooks.fetch_stats")@@ -72,9 +70,8 @@ def _load_cache():def _save_cache(stats):try:CACHE_DIR.mkdir(parents=True, exist_ok=True)- stats["_ts"] = time.time()- stats["_cache_version"] = CACHE_VERSION- CACHE_FILE.write_text(json.dumps(stats, indent=2))+ cached = {**stats, "_ts": time.time(), "_cache_version": CACHE_VERSION}+ CACHE_FILE.write_text(json.dumps(cached, indent=2))except Exception as e:log.warning("Could not write stats cache: %s", e)@@ -129,9 +126,7 @@ def _fetch_contributors():def _fetch_discord():- data, _ = _get(- f"https://discord.com/api/v9/invites/{DISCORD_INVITE}?with_counts=true"- )+ data, _ = _get(f"https://discord.com/api/v9/invites/{DISCORD_INVITE}?with_counts=true")return {"discord_members": _fmt(data["approximate_member_count"])}@@ -167,18 +162,23 @@ def _fetch_all():return stats+def fetch_stats():+ """Return the cached or freshly fetched build-time homepage statistics."""+ cached = _load_cache()+ if cached:+ return {key: value for key, value in cached.items() if not key.startswith("_")}++ stats = _fetch_all()+ _save_cache(stats)+ return stats++# ── MkDocs hook entry point ──────────────────────────────────────────────────+def on_config(config):log.info("Fetching live stats for home page...")-- cached = _load_cache()- if cached:- stats = {k: v for k, v in cached.items() if not k.startswith("_")}- else:- stats = _fetch_all()- _save_cache(stats)-+ stats = fetch_stats()config.setdefault("extra", {})["stats"] = statslog.info("Stats injected: %s", stats)return configdiff --git a/docs/mkdocs.yml b/docs/mkdocs.ymlindex 65313de49..4cd7ce61e 100644--- a/docs/mkdocs.yml+++ b/docs/mkdocs.yml@@ -7,6 +7,7 @@ repo_name: stanfordnlp/dspyedit_uri: blob/main/docs/docs/docs_dir: "docs/"+site_dir: "site/"nav:- Overview: index.md@@ -43,33 +44,33 @@ nav:- Build AI Programs with DSPy:- Overview: tutorials/build_ai_program/index.md- Managing Conversation History: tutorials/conversation_history/index.md- - Building AI Agents with DSPy: tutorials/customer_service_agent/index.ipynb- - Building AI Applications by Customizing DSPy Modules: tutorials/custom_module/index.ipynb- - Retrieval-Augmented Generation (RAG): tutorials/rag/index.ipynb- - Building RAG as Agent: tutorials/agents/index.ipynb- - Entity Extraction: tutorials/entity_extraction/index.ipynb+ - Building AI Agents with DSPy: tutorials/customer_service_agent/index.md+ - Building AI Applications by Customizing DSPy Modules: tutorials/custom_module/index.md+ - Retrieval-Augmented Generation (RAG): tutorials/rag/index.md+ - Building RAG as Agent: tutorials/agents/index.md+ - Entity Extraction: tutorials/entity_extraction/index.md- Classification: tutorials/classification/index.md- - Multi-Hop RAG: tutorials/multihop_search/index.ipynb+ - Multi-Hop RAG: tutorials/multihop_search/index.md- Privacy-Conscious Delegation: tutorials/papillon/index.md- - Program Of Thought: tutorials/program_of_thought/index.ipynb- - Image Generation Prompt iteration: tutorials/image_generation_prompting/index.ipynb- - Audio: tutorials/audio/index.ipynb+ - Program Of Thought: tutorials/program_of_thought/index.md+ - Image Generation Prompt iteration: tutorials/image_generation_prompting/index.md+ - Audio: tutorials/audio/index.md- Optimize AI Programs with DSPy:- Overview: tutorials/optimize_ai_program/index.md- - Math Reasoning: tutorials/math/index.ipynb- - Classification Finetuning: tutorials/classification_finetuning/index.ipynb- - Advanced Tool Use: tutorials/tool_use/index.ipynb- - Finetuning Agents: tutorials/games/index.ipynb+ - Math Reasoning: tutorials/math/index.md+ - Classification Finetuning: tutorials/classification_finetuning/index.md+ - Advanced Tool Use: tutorials/tool_use/index.md+ - Finetuning Agents: tutorials/games/index.md- Reflective Prompt Evolution with dspy.GEPA:- Overview: tutorials/gepa_ai_program/index.md- - GEPA for AIME (Math): tutorials/gepa_aime/index.ipynb- - GEPA for Structured Information Extraction for Enterprise Tasks: tutorials/gepa_facilitysupportanalyzer/index.ipynb- - GEPA for Privacy-Conscious Delegation: tutorials/gepa_papillon/index.ipynb- - GEPA for Code Backdoor Classification (AI control): tutorials/gepa_trusted_monitor/index.ipynb+ - GEPA for AIME (Math): tutorials/gepa_aime/index.md+ - GEPA for Structured Information Extraction for Enterprise Tasks: tutorials/gepa_facilitysupportanalyzer/index.md+ - GEPA for Privacy-Conscious Delegation: tutorials/gepa_papillon/index.md+ - GEPA for Code Backdoor Classification (AI control): tutorials/gepa_trusted_monitor/index.md- Experimental RL Optimization for DSPy:- Overview: tutorials/rl_ai_program/index.md- - RL for Privacy-Conscious Delegation: tutorials/rl_papillon/index.ipynb- - RL for Multi-Hop Research: tutorials/rl_multihop/index.ipynb+ - RL for Privacy-Conscious Delegation: tutorials/rl_papillon/index.md+ - RL for Multi-Hop Research: tutorials/rl_multihop/index.md- Tools, Development, and Deployment:- Overview: tutorials/core_development/index.md- Use MCP in DSPy: tutorials/mcp/index.md@@ -90,16 +91,6 @@ nav:- Email Information Extraction: tutorials/email_extraction/index.md- Code Generation for Unfamiliar Libraries: tutorials/sample_code_generation/index.md- Building a Creative Text-Based AI Game: tutorials/ai_text_game/index.md- - Community:- - Use Cases: community/use-cases.md- - Built with DSPy: community/built-with-dspy.md- - Resources: community/community-resources.md- - Contributing: community/how-to-contribute.md- - Normalized LM API Migration: community/normalized-lm-api-migration.md- - FAQ:- - FAQ: faqs.md- - Cheatsheet: cheatsheet.md-- API Reference:- API Reference: api/index.md- Adapters:@@ -197,9 +188,18 @@ nav:- inspect_history: api/utils/inspect_history.md- load: api/utils/load.md- streamify: api/utils/streamify.md+ - Community:+ - Use Cases: community/use-cases.md+ - Built with DSPy: community/built-with-dspy.md+ - Resources: community/community-resources.md+ - Contributing: community/how-to-contribute.md+ - Normalized LM API Migration: community/normalized-lm-api-migration.md+ - FAQ:+ - FAQ: faqs.md+ - Cheatsheet: cheatsheet.mdtheme:- name: material+ variant: classiccustom_dir: overridesfont:text: Inter@@ -242,14 +242,14 @@ extra_css:- stylesheets/extra.cssplugins:- - social- search:lang: enseparator: '[\s\-\.]+'+ - minify:+ minify_html: true- mkdocstrings:handlers:python:- paths: [".."]options:docstring_style: googleshow_source: true@@ -266,18 +266,10 @@ plugins:annotations_path: briefdocstring_section_style: tablemerge_init_into_class: true- rendering:- show_if_no_docstring: true- show_warnings: false- html_meta: false- - mkdocs-jupyter:- ignore_h1_titles: true- redirects:redirect_maps:# Redirect /intro/ to the main page"intro/index.md": "index.md"- "intro.md": "index.md"-"deep-dive/optimizers/bootstrap-fewshot.md": "api/optimizers/BootstrapFewShot.md""deep-dive/optimizers/bfrs.md": "api/optimizers/BootstrapFewShotWithRandomSearch.md""deep-dive/optimizers/BootstrapFinetune.md": "api/optimizers/BootstrapFinetune.md"@@ -286,14 +278,11 @@ plugins:"deep-dive/optimizers/LabeledFewShot.md": "api/optimizers/LabeledFewShot.md""deep-dive/optimizers/miprov2.md": "api/optimizers/MIPROv2.md""api/optimizers/GEPA/index.md": "api/optimizers/GEPA/overview.md"-"diving-deeper/tools-react-and-mcp.md": "diving-deeper/react.md"-- "docs/quick-start/getting-started-01.md": "tutorials/rag/index.ipynb"- "docs/quick-start/getting-started-02.md": "tutorials/rag/index.ipynb"- "quick-start/getting-started-01.md": "tutorials/rag/index.ipynb"- "quick-start/getting-started-02.md": "tutorials/rag/index.ipynb"-+ "docs/quick-start/getting-started-01.md": "tutorials/rag/index.md"+ "docs/quick-start/getting-started-02.md": "tutorials/rag/index.md"+ "quick-start/getting-started-01.md": "tutorials/rag/index.md"+ "quick-start/getting-started-02.md": "tutorials/rag/index.md""community/community-ports.md": "community/built-with-dspy.md""production/companies.md": "community/use-cases.md"@@ -314,44 +303,17 @@ plugins:# Redirect old numbered Getting Started URLs to the new kebab-case paths"getting_started/01_program_dont_prompt.md": "getting-started/program-dont-prompt.md"- "getting_started/02_installation.md": "getting-started/installation.md"- "getting_started/03_first_program.md": "getting-started/first-program.md"+ "getting_started/02_installation.md": "getting-started/installation.md"+ "getting_started/03_first_program.md": "getting-started/first-program.md""getting_started/04_expanding_signatures.md": "getting-started/expanding-signatures.md""getting_started/05_class_based_signatures.md": "getting-started/class-based-signatures.md"- "getting_started/06_changing_modules.md": "getting-started/changing-modules.md"- "getting_started/07_react_and_tools.md": "getting-started/react-and-tools.md"- "getting_started/08_composing_modules.md": "getting-started/composing-modules.md"- "getting_started/09_metrics.md": "getting-started/metrics.md"- "getting_started/10_gepa_optimization.md": "getting-started/gepa-optimization.md"+ "getting_started/06_changing_modules.md": "getting-started/changing-modules.md"+ "getting_started/07_react_and_tools.md": "getting-started/react-and-tools.md"+ "getting_started/08_composing_modules.md": "getting-started/composing-modules.md"+ "getting_started/09_metrics.md": "getting-started/metrics.md"+ "getting_started/10_gepa_optimization.md": "getting-started/gepa-optimization.md""getting_started/11_saving_and_loading.md": "getting-started/saving-and-loading.md"- "getting_started/12_where_to_go_next.md": "getting-started/where-to-go-next.md"- - llmstxt:- markdown_description: >- DSPy is the framework for programming—rather than prompting—language models.- DSPy unifies techniques for prompting, fine-tuning, reasoning, tool use, and evaluation of LMs.- It provides a systematic approach to building AI applications through composable modules,- optimization techniques, and evaluation frameworks.- sections:- Get Started:- - index.md: DSPy overview and quick start guide- Getting Started:- - getting-started/**.md- Diving Deeper:- - diving-deeper/**.md- Tutorials - Docs:- - tutorials/**.md- Tutorials - Notebooks:- - tutorials/**.ipynb- Community:- - community/**.md- FAQ:- - faqs.md: Common questions on DSPy usage, comparisons, optimization, and debugging- - cheatsheet.md: DSPy cheatsheet for quick reference- API Reference:- - api/**.md--hooks:- - hooks/fetch_stats.py+ "getting_started/12_where_to_go_next.md": "getting-started/where-to-go-next.md"extra:version:@@ -388,9 +350,6 @@ markdown_extensions:- pymdownx.mark- attr_list- md_in_html- - pymdownx.emoji:- emoji_index: !!python/name:material.extensions.emoji.twemoji- emoji_generator: !!python/name:material.extensions.emoji.to_svgcopyright: |© 2026 <a href="https://github.com/stanfordnlp" target="_blank" rel="noopener">DSPy</a>diff --git a/docs/overrides/home.html b/docs/overrides/home.htmlindex 14738e8f5..0a30b6737 100644--- a/docs/overrides/home.html+++ b/docs/overrides/home.html@@ -17,9 +17,11 @@<div class="hp-hero-text"><div class="hp-hero-badge"><span class="hp-dot"></span>- DSPy {{ config.extra.stats.release_version }} — {{ config.extra.stats.release_blurb }}- <span style="color:var(--hp-fg-3)">·</span>- <a href="https://github.com/stanfordnlp/dspy/releases">learn more →</a>+ <span>+ DSPy {{ config.extra.stats.release_version }} — {{ config.extra.stats.release_blurb }}+ <span style="color:var(--hp-fg-3)">·</span>+ <a href="https://github.com/stanfordnlp/dspy/releases">learn more →</a>+ </span></div><h1 class="hp-hero-title">diff --git a/docs/overrides/partials/tabs.html b/docs/overrides/partials/tabs.htmldeleted file mode 100644index 404593ac3..000000000--- a/docs/overrides/partials/tabs.html+++ /dev/null@@ -1,58 +0,0 @@-<!--- Copyright (c) 2016-2023 Martin Donath <[email protected]>-- Permission is hereby granted, free of charge, to any person obtaining a copy- of this software and associated documentation files (the "Software"), to- deal in the Software without restriction, including without limitation the- rights to use, copy, modify, merge, publish, distribute, sublicense, and/or- sell copies of the Software, and to permit persons to whom the Software is- furnished to do so, subject to the following conditions:-- The above copyright notice and this permission notice shall be included in- all copies or substantial portions of the Software.-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,- FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS- IN THE SOFTWARE.--->--{% import "partials/tabs-item.html" as item with context %}--<!-- Navigation tabs -->-<nav- class="md-tabs"- aria-label="{{ lang.t('tabs') }}"- data-md-component="tabs"->- <div class="md-tabs__inner md-grid">-- <!-- Adds tab on right side of header -->- {% if "FAQ" %}- <ul class="md-tabs__list" style="float: right;">- <li class="md-tabs__item">- <a href="/community/use-cases/" class="md-tabs__link">- Community- </a>- </li>- <li class="md-tabs__item">- <a href="/faqs/" class="md-tabs__link">- FAQ- </a>- </li>- </ul>- {% endif %}-- <!-- Original tabbed sections -->- <ul class="md-tabs__list">- {% for nav_item in nav %}- {% if nav_item.title not in ["FAQ", "Community"] %}- {{ item.render(nav_item) }}- {% endif %}- {% endfor %}- </ul>- </div>-</nav>diff --git a/docs/requirements.txt b/docs/requirements.txtindex 574cae0f9..9d7bbeb17 100644--- a/docs/requirements.txt+++ b/docs/requirements.txt@@ -1,11 +1,8 @@-git+https://github.com/stanfordnlp/dspy.git-mkdocs-material-mkdocs-jupyter-mkdocs-material[imaging]-mkdocs-redirects-mkdocstrings-mkdocstrings-python-mkdocs-llmstxt>=0.5.0+mkdocstrings==1.0.6+mkdocstrings-python==2.0.7+nbconvert==7.17.1+pillow==12.3.0+zensical==0.0.59mike==2.2.0urllib3==2.7.0mistune==3.3.4diff --git a/docs/scripts/build_docs.py b/docs/scripts/build_docs.pyindex d10e12734..65434875a 100644--- a/docs/scripts/build_docs.py+++ b/docs/scripts/build_docs.py@@ -14,6 +14,12 @@ import sysimport tempfilefrom pathlib import Path+if __package__:+ from .zensical_build import build_zensical_site+else: # Direct script execution from the deployed docs repository.+ from zensical_build import build_zensical_site++RELEASE_VERSION = re.compile(r"^(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(?:(?:a|b|rc)\d+)?$")@@ -57,8 +63,7 @@ def patched_config(config: Path, identifier: str, *, edit_ref: str | None = Nonetext, edit_count = re.subn(r"(?m)^edit_uri:\s*.*$", f"edit_uri: blob/{edit_ref}/docs/docs/", text, count=1)if edit_count != 1:raise RuntimeError(f"could not patch edit_uri in {config}")- # Release API reference must import the installed release artifact, not- # preferentially resolve the source checkout through mkdocstrings.+ # Release API docs must import the installed wheel, not this checkout.text = re.sub(r'(?m)^[ \t]+paths:\s*\[\s*["\x27]?\.\.["\x27]?\s*\][ \t]*\n', "", text, count=1)if not re.search(r"(?m)^\s+provider:\s*mike\s*$", text):version_config = " version:\n provider: mike\n alias: true\n"@@ -74,7 +79,7 @@ def patched_config(config: Path, identifier: str, *, edit_ref: str | None = Nonedef remove_source_maps(site: Path) -> dict[str, int]:- """Remove browser source maps from the generated site."""+ """Remove browser source maps after Zensical performs native minification."""before = sum(path.stat().st_size for path in site.rglob("*") if path.is_file())source_maps = list(site.rglob("*.map"))for path in source_maps:@@ -151,11 +156,11 @@ def installed_packages() -> dict[str, str]:def renderer_version() -> str:- return importlib.metadata.version("mkdocs-material")+ return importlib.metadata.version("zensical")def validate_release_site(site: Path, config: Path, version: str) -> None:- expected = (site / "index.html", site / "api" / "index.html", site / "search" / "search_index.json")+ expected = (site / "index.html", site / "api" / "index.html", site / "search.json", site / "llms.txt")missing = [str(path.relative_to(site)) for path in expected if not path.exists()]if missing:raise RuntimeError(f"release site is missing required output: {', '.join(missing)}")@@ -178,13 +183,9 @@ def validate_release_site(site: Path, config: Path, version: str) -> None:if missing_notebooks:raise RuntimeError(f"notebooks were not rendered: {', '.join(missing_notebooks)}")- config_text = config.read_text()- if re.search(r"(?m)^\s*- social\s*$", config_text):- cards = site / "assets" / "images" / "social"- if not cards.exists() or not any(cards.rglob("*.png")) or 'property="og:image"' not in home:- raise RuntimeError("social cards or Open Graph metadata were not generated")- if re.search(r"(?m)^\s*- llmstxt:\s*$", config_text) and not (site / "llms.txt").exists():- raise RuntimeError("mkdocs-llmstxt was configured but llms.txt was not generated")+ cards = site / "assets" / "images" / "social-zensical"+ if not cards.exists() or not any(cards.rglob("*.png")) or 'property="og:image"' not in home:+ raise RuntimeError("social cards or Open Graph metadata were not generated")try:dspy_version = importlib.metadata.version("dspy")@@ -207,21 +208,7 @@ def build(identifier = version or "current"effective_config = patched_config(config, identifier, edit_ref=version)try:- subprocess.run(- [- sys.executable,- "-m",- "mkdocs",- "build",- "--clean",- "--config-file",- str(effective_config),- "--site-dir",- str(output),- ],- cwd=config.parent,- check=True,- )+ build_zensical_site(config=effective_config, output=output, python=Path(sys.executable))finally:effective_config.unlink(missing_ok=True)@@ -242,7 +229,7 @@ def build("source_tag": version,"source_commit": source_commit,"source_commit_time": git_value(repository, "show", "-s", "--format=%cI", source_commit),- "renderer": "material",+ "renderer": "zensical","renderer_version": renderer_version(),"package_source": package_source,"package_artifact": artifact.name,@@ -253,8 +240,7 @@ def build("intentional_differences": ["The renderer's Mike version selector is enabled in a transient build configuration.","Build provenance metadata added under _meta/build.json.",- "Browser source maps are omitted from production snapshots.",- "Original deployment dependencies were not locked; non-DSPy dependencies are reconstructed as of the tag date.",+ "Generated HTML is minified and source maps are omitted from production snapshots.",],}metadata_dir = output / "_meta"diff --git a/docs/scripts/publish_versioned_docs.py b/docs/scripts/publish_versioned_docs.pyindex 2b0a4f820..036bbd7f6 100644--- a/docs/scripts/publish_versioned_docs.py+++ b/docs/scripts/publish_versioned_docs.py@@ -185,7 +185,7 @@ def publish_site(alias_type=commands.AliasType.redirect,branch=branch,message=message,- set_props=[("renderer", "material"), ("package_source", package_source)],+ set_props=[("renderer", "zensical"), ("package_source", package_source)],):passroot = branch_file(repository, branch, "index.html")diff --git a/docs/scripts/zensical_build.py b/docs/scripts/zensical_build.pynew file mode 100644index 000000000..343efec31--- /dev/null+++ b/docs/scripts/zensical_build.py@@ -0,0 +1,368 @@+#!/usr/bin/env python3+"""Build DSPy documentation with Zensical from a disposable prepared project."""++from __future__ import annotations++import gzip+import hashlib+import importlib.util+import json+import os+import re+import shutil+import subprocess+import sys+import tempfile+import textwrap+from html import escape+from html.parser import HTMLParser+from pathlib import Path+from urllib.parse import urljoin++import yaml+++def load_config(path: Path) -> dict[str, object]:+ return dict(yaml.safe_load(path.read_text()))+++def write_config(path: Path, config: dict[str, object]) -> None:+ path.write_text(yaml.safe_dump(config, sort_keys=False, allow_unicode=True))+++def nav_entries(value: object) -> dict[str, str]:+ entries: dict[str, str] = {}+ if isinstance(value, list):+ for item in value:+ entries.update(nav_entries(item))+ elif isinstance(value, dict):+ for title, item in value.items():+ if isinstance(item, str) and item.endswith((".md", ".ipynb")):+ entries[item] = str(title)+ else:+ entries.update(nav_entries(item))+ return entries+++def route_for_source(path: str) -> str:+ source = Path(path)+ route = (+ source.parent.as_posix().strip("/")+ if source.name == "index.md"+ else source.with_suffix("").as_posix().strip("/")+ )+ return f"/{route}/" if route and route != "." else "/"+++def fetch_stats(project: Path) -> dict[str, object]:+ """Run the existing MkDocs stats hook for Zensical's template context."""+ hook = project / "hooks" / "fetch_stats.py"+ spec = importlib.util.spec_from_file_location("dspy_docs_fetch_stats", hook)+ if spec is None or spec.loader is None:+ raise RuntimeError(f"cannot load {hook}")+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return dict(module.fetch_stats())+++def prepare_config(config: dict[str, object], stats: dict[str, object]) -> dict[str, object]:+ prepared = dict(config)+ extra = dict(prepared.get("extra", {}))+ extra["stats"] = stats+ prepared["extra"] = extra+ return prepared+++def redirect_maps(config: dict[str, object]) -> dict[str, str]:+ for plugin in config.get("plugins", []):+ if isinstance(plugin, dict) and "redirects" in plugin:+ return dict(plugin["redirects"].get("redirect_maps", {}))+ return {}+++def remove_redirect_sources(docs: Path, config: dict[str, object]) -> None:+ """Reserve legacy routes for the static redirect adapter."""+ for source in redirect_maps(config):+ (docs / source).unlink(missing_ok=True)+++def redirect_document(target: str) -> str:+ encoded = json.dumps(target)+ escaped = escape(target, quote=True)+ return (+ '<!doctype html><html lang="en"><head><meta charset="utf-8">'+ f'<link rel="canonical" href="{escaped}">'+ f"<script>location.replace({encoded}+location.search+location.hash)</script>"+ f'<noscript><meta http-equiv="refresh" content="0; url={escaped}"></noscript>'+ f'</head><body><a href="{escaped}">Continue to the documentation</a></body></html>'+ )+++def write_redirects(site: Path, redirects: dict[str, str]) -> None:+ """Material's redirects plugin is not implemented by Zensical."""+ for source, target in redirects.items():+ route = route_for_source(source)+ destination = site / route.lstrip("/") / "index.html"+ destination.parent.mkdir(parents=True, exist_ok=True)+ target_route = route_for_source(target.replace(".ipynb", ".md"))+ relative = os.path.relpath(target_route.lstrip("/") or ".", route.lstrip("/") or ".")+ if relative == ".":+ relative = "../" if route != "/" else "./"+ elif not relative.endswith("/"):+ relative += "/"+ destination.write_text(redirect_document(relative))+++def convert_notebooks(docs: Path) -> set[str]:+ from nbconvert import MarkdownExporter++ exporter = MarkdownExporter()+ routes = set()+ for notebook in docs.rglob("*.ipynb"):+ relative = notebook.relative_to(docs).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"}+ )+ notebook.with_suffix(".md").write_text(body.replace("<details>", '<details markdown="1">'))+ for name, content in resources.get("outputs", {}).items():+ output = notebook.parent / name+ output.parent.mkdir(parents=True, exist_ok=True)+ output.write_bytes(content)+ notebook.unlink()+ 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")+ source.with_suffix(".md").write_text(+ f"# {source.stem.replace('_', ' ').title()}\n\n```python\n{source.read_text()}\n```\n"+ )+ return routes+++def add_missing_titles(docs: Path, entries: dict[str, str]) -> None:+ for source, title in entries.items():+ path = docs / source.replace(".ipynb", ".md")+ if path.name == "index.md" and path == docs / "index.md":+ continue+ if path.exists() and not re.search(r"(?m)^#\s+", path.read_text()):+ path.write_text(f"# {title}\n\n{path.read_text()}")+++def source_title(source: Path) -> str:+ if source.suffix == ".ipynb":+ notebook = json.loads(source.read_text())+ text = "\n".join("".join(cell["source"]) for cell in notebook["cells"] if cell["cell_type"] == "markdown")+ else:+ text = source.read_text(errors="replace")+ match = re.search(r"(?m)^#\s+(.+?)\s*$", text)+ return re.sub(r"\s*\{[^}]+\}\s*$", "", match.group(1)) if match else source.stem.replace("-", " ").title()+++def matching_sources(docs: Path, pattern: str) -> list[Path]:+ if "**." in pattern:+ prefix, suffix = pattern.split("**.", 1)+ return sorted((docs / prefix).rglob(f"*.{suffix}"))+ path = docs / pattern+ return [path] if path.exists() else []+++def generate_llms(docs: Path, output: Path, site_url: str, settings: dict[str, object]) -> None:+ parts = [+ "# DSPy",+ "",+ "> DSPy is the framework for programming—rather than prompting—language models.",+ "",+ str(settings["markdown_description"]).strip(),+ "",+ ]+ for section, entries in settings["sections"].items():+ parts.extend((f"## {section}", ""))+ for entry in entries:+ pattern, description = next(iter(entry.items())) if isinstance(entry, dict) else (entry, None)+ for source in matching_sources(docs, pattern):+ route = route_for_source(source.relative_to(docs).as_posix().replace(".ipynb", ".md"))+ target = "index.md" if route == "/" else f"{route.lstrip('/')}index.md"+ line = f"- [{source_title(source)}]({urljoin(site_url, target)})"+ parts.append(f"{line}: {description}" if description else line)+ parts.append("")+ output.write_text("\n".join(parts))+++class HeadParser(HTMLParser):+ def __init__(self) -> None:+ super().__init__()+ self.metadata: dict[str, str] = {}++ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:+ values = dict(attrs)+ if tag == "link" and values.get("rel") == "canonical" and values.get("href"):+ self.metadata["canonical"] = values["href"]+ elif tag == "meta":+ key = values.get("property") or values.get("name")+ if key and values.get("content"):+ self.metadata[key] = values["content"]+++def navigation_titles(config: dict[str, object]) -> dict[str, str]:+ titles = {"/": str(config.get("site_name", "DSPy"))}+ for source, title in nav_entries(config.get("nav", [])).items():+ route = route_for_source(source.replace(".ipynb", ".md"))+ if route != "/":+ titles[route] = title+ return titles+++def page_titles(config: dict[str, object], docs: Path) -> dict[str, str]:+ titles = navigation_titles(config)+ sources = [*docs.rglob("*.md"), *docs.rglob("*.ipynb"), *docs.rglob("*.py")]+ for source in sources:+ relative = source.relative_to(docs).as_posix()+ route = route_for_source(relative.replace(".ipynb", ".md").replace(".py", ".md"))+ titles.setdefault(route, source_title(source))+ return titles+++def social_cards(site: Path, site_url: str, titles: dict[str, str], logo: Path) -> None:+ from PIL import Image, ImageDraw, ImageFont++ card_dir = site / "assets" / "images" / "social-zensical"+ card_dir.mkdir(parents=True, exist_ok=True)+ font = ImageFont.truetype("DejaVuSans.ttf", 32)+ title_font = ImageFont.truetype("DejaVuSans.ttf", 84)+ description_font = ImageFont.truetype("DejaVuSans.ttf", 25)+ logo_image = Image.open(logo).convert("RGBA").resize((140, 140))+ for page in site.rglob("*.html"):+ html = page.read_text()+ if "<article" not in html:+ continue+ relative = page.relative_to(site)+ route = "/" if relative == Path("index.html") else f"/{relative.parent.as_posix()}/"+ parser = HeadParser()+ parser.feed(html)+ title = titles.get(route, Path(route.strip("/")).name.replace("-", " ").title() or "DSPy")+ description = parser.metadata.get(+ "description", "The framework for programming—rather than prompting—language models."+ )+ card = card_dir / f"{hashlib.sha256(route.encode()).hexdigest()[:16]}.png"+ image = Image.new("RGB", (1200, 630), "white")+ draw = ImageDraw.Draw(image)+ draw.text((64, 65), "DSPy", fill="black", font=font)+ lines = textwrap.wrap(title, width=23)+ draw.multiline_text((64, 270 if len(lines) > 1 else 170), "\n".join(lines), fill="black", font=title_font)+ image.paste(logo_image, (995, 65), logo_image)+ draw.multiline_text(+ (64, 515), "\n".join(textwrap.wrap(description, width=48)), fill="black", font=description_font, spacing=8+ )+ image.save(card)++ card_url = urljoin(site_url, f"assets/images/social-zensical/{card.name}")+ page_url = urljoin(site_url, route.lstrip("/"))+ metadata = {+ "og:type": "website",+ "og:title": title if route == "/" else f"{title} - DSPy",+ "og:description": description,+ "og:url": page_url,+ "og:image": card_url,+ "og:image:type": "image/png",+ "og:image:width": "1200",+ "og:image:height": "630",+ "twitter:card": "summary_large_image",+ "twitter:title": title if route == "/" else f"{title} - DSPy",+ "twitter:description": description,+ "twitter:image": card_url,+ }+ managed_images = {"og:image", "twitter:image"}+ html = re.sub(+ r'<meta\b(?=[^>]*(?:property|name)=["\'](?:og:image|twitter:image)["\'])[^>]*>\s*',+ "",+ html,+ flags=re.IGNORECASE,+ )+ tags = "".join(+ f'<meta {"name" if key.startswith("twitter:") else "property"}="{escape(key)}" '+ f'content="{escape(value, quote=True)}">\n'+ for key, value in metadata.items()+ if key in managed_images or key not in parser.metadata+ )+ page.write_text(html.replace("</head>", f"{tags}</head>", 1))+++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")+ missing = [path for path in required if not (site / path).is_file()]+ missing.extend(route for route in notebook_routes if not (site / route).is_file())+ missing.extend(+ route_for_source(source).lstrip("/") + "index.html"+ for source in redirects+ if not (site / (route_for_source(source).lstrip("/") + "index.html")).is_file()+ )+ if missing:+ raise RuntimeError(f"Zensical output is missing required files: {', '.join(sorted(missing))}")++ search = json.loads((site / "search.json").read_text())+ if not search.get("items"):+ raise RuntimeError("Zensical search index is empty")+ if gzip.decompress((site / "sitemap.xml.gz").read_bytes()) != (site / "sitemap.xml").read_bytes():+ raise RuntimeError("compressed sitemap does not match sitemap.xml")+ home = (site / "index.html").read_text()+ cards = site / "assets" / "images" / "social-zensical"+ if not any(cards.glob("*.png")) or 'property="og:image"' not in home:+ raise RuntimeError("social cards or Open Graph metadata were not generated")+++def build_zensical_site(+ *,+ config: Path,+ output: Path,+ python: Path = Path(sys.executable),+ keep_project: Path | None = None,+) -> set[str]:+ source_project = config.parent+ source_config = load_config(config)+ build_config = load_config(source_project / "build.yml")+ llms = dict(build_config["llms"])+ source_docs = source_project / str(source_config.get("docs_dir", "docs"))+ titles = page_titles(source_config, source_docs)++ temporary = None if keep_project else tempfile.TemporaryDirectory(prefix="dspy-zensical-build-")+ project = keep_project.resolve() if keep_project else Path(temporary.name) / "project"+ shutil.rmtree(project, ignore_errors=True)+ shutil.copytree(+ source_project, project, ignore=shutil.ignore_patterns("site", ".cache", "__pycache__", ".zensical-*")+ )+ try:+ prepared = prepare_config(source_config, fetch_stats(source_project))+ prepared_config = project / "zensical.generated.yml"+ write_config(prepared_config, prepared)+ prepared_docs = project / str(prepared.get("docs_dir", "docs"))+ remove_redirect_sources(prepared_docs, prepared)+ notebook_routes = convert_notebooks(prepared_docs)+ add_missing_titles(prepared_docs, nav_entries(prepared.get("nav", [])))++ subprocess.run(+ [str(python), "-m", "zensical", "build", "--clean", "--config-file", prepared_config],+ cwd=project,+ check=True,+ )+ built = project / str(prepared["site_dir"])+ shutil.rmtree(output, ignore_errors=True)+ shutil.copytree(built, output)+ write_redirects(output, redirect_maps(prepared))+ generate_llms(+ source_project / str(source_config.get("docs_dir", "docs")),+ output / "llms.txt",+ str(source_config["site_url"]),+ llms,+ )+ social_cards(output, str(source_config["site_url"]), titles, project / "docs" / "static" / "img" / "logo.png")+ sitemap = output / "sitemap.xml"+ with gzip.open(output / "sitemap.xml.gz", "wb") as compressed:+ compressed.write(sitemap.read_bytes())+ home = output / "index.html"+ home.write_text(re.sub(r"<title>Index\s+-\s+DSPy</title>", "<title>DSPy</title>", home.read_text(), count=1))+ validate_output(output, notebook_routes, redirect_maps(prepared))+ return notebook_routes+ finally:+ if temporary:+ temporary.cleanup()diff --git a/docs/versioning/README.md b/docs/versioning/README.mdindex 05c17f7c2..82fa5c1b6 100644--- a/docs/versioning/README.md+++ b/docs/versioning/README.md@@ -15,8 +15,8 @@ and are hidden from the picker. Mike owns `versions.json`, thedefault redirect, aliases, and version directories on the generated`versioned-docs` branch in `krypticmouse/dspy-docs`.-Historical snapshots use Material for MkDocs. Current records its renderer in-`versions.json`; stored static versions do not need to share a renderer.+Historical snapshots use Material for MkDocs, while Current and future release+snapshots use Zensical. Stored static versions do not need to share a renderer.## Deployment and promotion@@ -25,6 +25,10 @@ to production `master` through reviewed pull requests in`krypticmouse/dspy-docs`. Production's `versions.json` is the activation markerfor Mike publication; a candidate branch alone never changes production.+Renderer migrations are built on `versioned-docs` first. After that branch is+reviewed and promoted, the Current workflow's explicit publication target is+changed to `master`. There is no implicit promotion based on site metadata.+Existing unversioned page URLs remain valid. Publishing Current generates rootredirect pages such as `/api/` → `/current/api/`, and each build scopeshand-authored root-relative links to its own version so an old page cannot@@ -72,3 +76,29 @@ Minor aliases contain redirects rather than duplicate assets. Productionbuilds remove source maps. Git deduplicates byte-identical objects in thedeployment repository. Browsers request only the selected page and its assets;they do not download the aggregate repository.++## Zensical feature ownership++Zensical owns rendering, navigation, search, minification, API reference, and+sitemap generation through its native configuration. The small compatibility+builder owns only features Zensical does not provide:++| Existing feature | Implementation |+| --- | --- |+| Notebooks | pre-render with `nbconvert` in a disposable source tree |+| Redirects | emit static redirects from the configured route map |+| Social cards | generate per-page cards and inject matching metadata |+| `llms.txt` | generate from the same configured source inventory |+| Build-time statistics | run the existing fetcher into the disposable config |+| Compressed sitemap | gzip Zensical's generated `sitemap.xml` |++Redirect sources that overlap legacy pages are removed only from the disposable+tree before the static redirects are emitted. Source files in the repository+are unchanged.++Unit tests exercise each compatibility transform directly. The documentation+pull-request job then builds the complete site, making the native Zensical+configuration and all compatibility steps executable review evidence. Visual+review covers representative desktop and mobile pages; typography, spacing,+wrapping, search ranking, and card appearance may change without dropping a+feature.diff --git a/docs/versioning/header.css b/docs/versioning/header.cssindex d99c2a31b..9e728b363 100644--- a/docs/versioning/header.css+++ b/docs/versioning/header.css@@ -50,7 +50,6 @@right: 0;left: auto;width: 8rem;- max-height: 19rem;margin-right: 0;margin-left: 0;padding: 0;diff --git a/tests/docs/test_mkdocs_links.py b/tests/docs/test_mkdocs_links.pyindex f2630c894..1b1f6fbbb 100644--- a/tests/docs/test_mkdocs_links.py+++ b/tests/docs/test_mkdocs_links.py@@ -1,7 +1,7 @@import os-def test_nav_files_exist():+def test_nav_sources_exist():# Read mkdocs.ymldocs_dir = os.path.join(os.path.dirname(__file__), "..", "..", "docs", "docs")yaml_path = os.path.join(os.path.dirname(__file__), "..", "..", "docs", "mkdocs.yml")@@ -25,10 +25,13 @@ def test_nav_files_exist():if md_file.endswith(".md"):md_files.append(md_file)- # Check if files exist+ # Notebook and Python pages are converted to Markdown in the disposable+ # Zensical project, so their nav entries name the generated .md path.missing = []for file in md_files:- if not os.path.exists(os.path.join(docs_dir, file)):+ source = os.path.join(docs_dir, file)+ generated_sources = [os.path.splitext(source)[0] + suffix for suffix in (".ipynb", ".py")]+ if not os.path.exists(source) and not any(os.path.exists(candidate) for candidate in generated_sources):missing.append(file)print("\nChecking files in:", docs_dir)diff --git a/tests/docs/test_versioned_docs.py b/tests/docs/test_versioned_docs.pyindex d78d24d5b..4fabd151f 100644--- a/tests/docs/test_versioned_docs.py+++ b/tests/docs/test_versioned_docs.py@@ -2,6 +2,7 @@ import argparseimport importlib.utilimport jsonimport subprocess+from pathlib import Pathimport pytest@@ -18,6 +19,17 @@ from docs.scripts.publish_versioned_docs import publish_site, version_tuplerequires_mike = pytest.mark.skipif(importlib.util.find_spec("mike") is None, reason="Mike is a docs-only dependency")+def test_current_workflow_publishes_to_production_branch():+ workflow = Path(".github/workflows/docs-push.yml").read_text()+ checkout = workflow.split(" - name: Check out documentation deployment", 1)[1].split(" - name:", 1)[0]+ publish = workflow.split(" - name: Publish Current through Mike", 1)[1]++ assert "ref: master" in checkout+ assert "--branch master" in publish+ assert "push origin master" in publish+ assert "versioned-docs" not in checkout + publish++def make_site(root, content: str):site = root / "site"nested = site / "guide"diff --git a/tests/docs/test_zensical_build.py b/tests/docs/test_zensical_build.pynew file mode 100644index 000000000..a01173e7a--- /dev/null+++ b/tests/docs/test_zensical_build.py@@ -0,0 +1,214 @@+import gzip+import json+from pathlib import Path++import pytest++from docs.hooks import fetch_stats as stats_hook+from docs.scripts.zensical_build import (+ add_missing_titles,+ convert_notebooks,+ generate_llms,+ load_config,+ nav_entries,+ navigation_titles,+ prepare_config,+ redirect_maps,+ remove_redirect_sources,+ social_cards,+ validate_output,+ write_redirects,+)+++def test_zensical_configuration_is_native_and_keeps_build_compatibility_separate():+ project = Path(__file__).parents[2] / "docs"+ config = load_config(project / "mkdocs.yml")+ build = load_config(project / "build.yml")++ assert config["theme"]["variant"] == "classic"+ assert "name" not in config["theme"]+ assert [plugin if isinstance(plugin, str) else next(iter(plugin)) for plugin in config["plugins"]] == [+ "search",+ "minify",+ "mkdocstrings",+ "redirects",+ ]+ assert "hooks" not in config+ redirects = next(plugin["redirects"] for plugin in config["plugins"] if "redirects" in plugin)+ assert redirects["redirect_maps"]["intro/index.md"] == "index.md"+ assert "Tutorials - Notebooks" in build["llms"]["sections"]+++def test_extracts_navigation_titles(tmp_path):+ config = tmp_path / "mkdocs.yml"+ config.write_text(+ "nav:\n - Overview: index.md\n - Retrieval-Augmented Generation (RAG): tutorials/rag/index.md\n"+ )++ parsed = load_config(config)++ assert navigation_titles(parsed) == {+ "/": "DSPy",+ "/tutorials/rag/": "Retrieval-Augmented Generation (RAG)",+ }+++def test_adds_navigation_title_only_when_a_page_has_no_heading(tmp_path):+ docs = tmp_path / "docs"+ (docs / "tutorials" / "classification").mkdir(parents=True)+ missing = docs / "tutorials" / "classification" / "index.md"+ missing.write_text("Page content\n")+ existing = docs / "guide.md"+ existing.write_text("# Existing\n")+ config = tmp_path / "mkdocs.yml"+ config.write_text("nav:\n - Classification: tutorials/classification/index.md\n - Guide: guide.md\n")++ add_missing_titles(docs, nav_entries(load_config(config)["nav"]))++ assert missing.read_text().startswith("# Classification\n\n")+ assert existing.read_text() == "# Existing\n"+++def test_notebook_conversion_preserves_python_pages(tmp_path):+ nbformat = pytest.importorskip("nbformat")+ notebook = nbformat.v4.new_notebook(cells=[nbformat.v4.new_markdown_cell("# Guide")])+ nbformat.write(notebook, tmp_path / "guide.ipynb")+ helper = tmp_path / "helper.py"+ helper.write_text("VALUE = 1\n")++ routes = convert_notebooks(tmp_path)++ assert routes == {"guide/index.html", "helper/index.html"}+ assert (tmp_path / "guide.md").exists()+ assert helper.exists()+ assert "```python\nVALUE = 1" in (tmp_path / "helper.md").read_text()+++def test_llms_generation_uses_the_configured_inventory(tmp_path):+ docs = tmp_path / "docs"+ (docs / "guides").mkdir(parents=True)+ (docs / "index.md").write_text("# DSPy\n")+ (docs / "guides" / "first.md").write_text("# First Guide\n")+ (docs / "excluded.md").write_text("# Excluded\n")+ output = tmp_path / "llms.txt"++ generate_llms(+ docs,+ output,+ "https://dspy.ai/",+ {+ "markdown_description": "Description",+ "sections": {+ "Home": [{"index.md": "Overview"}],+ "Guides": ["guides/**.md"],+ },+ },+ )++ result = output.read_text()+ assert "Description" in result+ assert "[DSPy](https://dspy.ai/index.md): Overview" in result+ assert "[First Guide](https://dspy.ai/guides/first/index.md)" in result+ assert "Excluded" not in result+++def test_public_stats_api_does_not_leak_cache_metadata(tmp_path, monkeypatch):+ cache = tmp_path / "stats.json"+ fetched = {"stars": "10k"}+ monkeypatch.setattr(stats_hook, "CACHE_DIR", tmp_path)+ monkeypatch.setattr(stats_hook, "CACHE_FILE", cache)+ monkeypatch.setattr(stats_hook, "_fetch_all", lambda: fetched)++ result = stats_hook.fetch_stats()++ assert result == {"stars": "10k"}+ assert fetched == {"stars": "10k"}+ assert stats_hook.fetch_stats() == {"stars": "10k"}+ assert set(json.loads(cache.read_text())) == {"stars", "_ts", "_cache_version"}+++def test_prepared_config_exposes_stats_without_mutating_source():+ source = {"extra": {"social": []}}++ prepared = prepare_config(source, {"stars": "10k"})++ assert prepared["extra"] == {"social": [], "stats": {"stars": "10k"}}+ assert source == {"extra": {"social": []}}+++def test_social_cards_replace_renderer_image_metadata(tmp_path):+ image = pytest.importorskip("PIL.Image")+ logo = tmp_path / "logo.png"+ image.new("RGBA", (16, 16), "red").save(logo)+ home = tmp_path / "index.html"+ home.write_text(+ "<html><head>"+ '<meta content="https://renderer.example/og.png" property="og:image">'+ '<meta name="twitter:image" content="https://renderer.example/twitter.png">'+ "</head><body><article>Home</article></body></html>"+ )++ social_cards(tmp_path, "https://dspy.ai/current/", {"/": "DSPy"}, logo)++ rendered = home.read_text()+ card = "https://dspy.ai/current/assets/images/social-zensical/8a5edab282632443.png"+ assert rendered.count('property="og:image"') == 1+ assert rendered.count('name="twitter:image"') == 1+ assert 'property="twitter:image"' not in rendered+ assert rendered.count(f'content="{card}"') == 2+ assert "renderer.example" not in rendered+++def test_redirect_sources_are_removed_only_from_prepared_tree(tmp_path):+ source = tmp_path / "learn" / "index.md"+ source.parent.mkdir()+ source.write_text("legacy content")+ config = {"plugins": [{"redirects": {"redirect_maps": {"learn/index.md": "index.md"}}}]}++ remove_redirect_sources(tmp_path, config)++ assert not source.exists()+ assert redirect_maps(config) == {"learn/index.md": "index.md"}+++def test_redirects_preserve_relative_navigation_query_and_fragment(tmp_path):+ write_redirects(+ tmp_path,+ {+ "learn/index.md": "getting-started/first-program.md",+ "api/old.md": "api/new/index.md",+ },+ )++ learn = (tmp_path / "learn" / "index.html").read_text()+ api = (tmp_path / "api" / "old" / "index.html").read_text()+ assert 'location.replace("../getting-started/first-program/"+location.search+location.hash)' in learn+ assert 'href="../getting-started/first-program/"' in learn+ assert 'location.replace("../new/"+location.search+location.hash)' in api+++def test_output_validation_covers_native_and_compatibility_features(tmp_path):+ required = ("index.html", "api/index.html", "llms.txt", "sitemap.xml")+ for relative in required:+ path = tmp_path / relative+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text('<article></article><meta property="og:image">')+ (tmp_path / "search.json").write_text(json.dumps({"items": [{"location": "/"}]}))+ with gzip.open(tmp_path / "sitemap.xml.gz", "wb") as compressed:+ compressed.write((tmp_path / "sitemap.xml").read_bytes())+ notebook = tmp_path / "tutorial" / "index.html"+ notebook.parent.mkdir()+ notebook.write_text("notebook")+ redirect = tmp_path / "old" / "index.html"+ redirect.parent.mkdir()+ redirect.write_text("redirect")+ cards = tmp_path / "assets" / "images" / "social-zensical"+ cards.mkdir(parents=True)+ (cards / "home.png").write_bytes(b"card")++ validate_output(tmp_path, {"tutorial/index.html"}, {"old.md": "index.md"})++ (tmp_path / "search.json").write_text(json.dumps({"items": []}))+ with pytest.raises(RuntimeError, match="search index is empty"):+ validate_output(tmp_path, {"tutorial/index.html"}, {"old.md": "index.md"})