Skip to content

armgit / dspy

Public Imported from GitHub
0

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.yml
index 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 build
run: |
- 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/site
detect-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 documentation
run: |
python docs/scripts/build_docs.py current \
diff --git a/docs/build.yml b/docs/build.yml
new file mode 100644
index 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/**.md
diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css
index 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.py
index 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 logging
import re
import time
-import logging
from datetime import datetime, timedelta
from pathlib import Path
from urllib.request import Request, urlopen
-from urllib.error import URLError
log = 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"] = stats
log.info("Stats injected: %s", stats)
return config
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 65313de49..4cd7ce61e 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -7,6 +7,7 @@ repo_name: stanfordnlp/dspy
edit_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.md
theme:
- name: material
+ variant: classic
custom_dir: overrides
font:
text: Inter
@@ -242,14 +242,14 @@ extra_css:
- stylesheets/extra.css
plugins:
- - social
- search:
lang: en
separator: '[\s\-\.]+'
+ - minify:
+ minify_html: true
- mkdocstrings:
handlers:
python:
- paths: [".."]
options:
docstring_style: google
show_source: true
@@ -266,18 +266,10 @@ plugins:
annotations_path: brief
docstring_section_style: table
merge_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_svg
copyright: |
&copy; 2026 <a href="https://github.com/stanfordnlp" target="_blank" rel="noopener">DSPy</a>
diff --git a/docs/overrides/home.html b/docs/overrides/home.html
index 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 }} &mdash; {{ config.extra.stats.release_blurb }}
- <span style="color:var(--hp-fg-3)">&middot;</span>
- <a href="https://github.com/stanfordnlp/dspy/releases">learn more &rarr;</a>
+ <span>
+ DSPy {{ config.extra.stats.release_version }} &mdash; {{ config.extra.stats.release_blurb }}
+ <span style="color:var(--hp-fg-3)">&middot;</span>
+ <a href="https://github.com/stanfordnlp/dspy/releases">learn more &rarr;</a>
+ </span>
</div>
<h1 class="hp-hero-title">
diff --git a/docs/overrides/partials/tabs.html b/docs/overrides/partials/tabs.html
deleted file mode 100644
index 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.txt
index 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.59
mike==2.2.0
urllib3==2.7.0
mistune==3.3.4
diff --git a/docs/scripts/build_docs.py b/docs/scripts/build_docs.py
index d10e12734..65434875a 100644
--- a/docs/scripts/build_docs.py
+++ b/docs/scripts/build_docs.py
@@ -14,6 +14,12 @@ import sys
import tempfile
from 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 = None
text, 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 = None
def 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.py
index 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)],
):
pass
root = branch_file(repository, branch, "index.html")
diff --git a/docs/scripts/zensical_build.py b/docs/scripts/zensical_build.py
new file mode 100644
index 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.md
index 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`, the
default 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 marker
for 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 root
redirect pages such as `/api/` → `/current/api/`, and each build scopes
hand-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. Production
builds remove source maps. Git deduplicates byte-identical objects in the
deployment 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.css
index 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.py
index 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.yml
docs_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.py
index d78d24d5b..4fabd151f 100644
--- a/tests/docs/test_versioned_docs.py
+++ b/tests/docs/test_versioned_docs.py
@@ -2,6 +2,7 @@ import argparse
import importlib.util
import json
import subprocess
+from pathlib import Path
import pytest
@@ -18,6 +19,17 @@ from docs.scripts.publish_versioned_docs import publish_site, version_tuple
requires_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.py
new file mode 100644
index 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"})