DSPy: The framework for programming—not prompting—language models
Python
docs: automate Current and release snapshots (#10317)
Isaac Miller208e751f571d
diff --git a/.github/workflows/build_and_release.yml b/.github/workflows/build_and_release.ymlindex 52b1e30e3..e8a82f91f 100644--- a/.github/workflows/build_and_release.yml+++ b/.github/workflows/build_and_release.yml@@ -134,6 +134,12 @@ jobs:(cd "$RUNNER_TEMP" && python -c 'import dspy; assert dspy.PythonInterpreter().execute("6 * 7") == 42')deactivaterm -r test_before_pypi+ - name: Preserve the exact release wheel for documentation+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2+ with:+ name: dspy-release-wheel+ path: dist/*.whl+ if-no-files-found: error- name: Publish distribution 📦 to PyPI (dspy)uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1with:@@ -158,6 +164,112 @@ jobs:with:attestations: falsepackages-dir: .github/.internal_dspyai/dist/++ release-docs:+ needs: [extract-tag, build-and-publish-pypi]+ if: github.repository_owner == 'stanfordnlp'+ runs-on: ubuntu-latest+ permissions:+ contents: read+ steps:+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0+ with:+ persist-credentials: false+ fetch-depth: 0+ - name: Check whether this is a documentation release+ id: publishable+ env:+ VERSION: ${{ needs.extract-tag.outputs.version }}+ run: |+ if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]] && (( ${VERSION%%.*} >= 3 )); then+ echo "publish=true" >> "$GITHUB_OUTPUT"+ else+ echo "publish=false" >> "$GITHUB_OUTPUT"+ fi+ - name: Set up Python 3.11+ if: steps.publishable.outputs.publish == 'true'+ uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0+ with:+ python-version: "3.11"+ - name: Download exact production wheel+ if: steps.publishable.outputs.publish == 'true'+ uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0+ with:+ name: dspy-release-wheel+ path: release-wheel+ - name: Install documentation dependencies and release wheel+ if: steps.publishable.outputs.publish == 'true'+ run: python -m pip install -r docs/requirements.txt release-wheel/*.whl+ - name: Verify API introspection uses the release wheel+ if: steps.publishable.outputs.publish == 'true'+ run: |+ cd "$RUNNER_TEMP"+ env -u PYTHONPATH PYTHONSAFEPATH=1 python -P - <<'PY'+ import site+ from pathlib import Path++ import dspy++ module = Path(dspy.__file__).resolve()+ site_packages = [Path(root).resolve() for root in site.getsitepackages()]+ if not any(module.is_relative_to(root) for root in site_packages):+ raise SystemExit(f"DSPy resolved outside site-packages: {module}")+ print(f"DSPy API source: {module}")+ PY+ - name: Build immutable release documentation+ if: steps.publishable.outputs.publish == 'true'+ env:+ VERSION: ${{ needs.extract-tag.outputs.version }}+ run: |+ cd "$RUNNER_TEMP"+ env PYTHONPATH="$GITHUB_WORKSPACE/docs/scripts" PYTHONSAFEPATH=1 python -P \+ "$GITHUB_WORKSPACE/docs/scripts/build_docs.py" release \+ --config "$GITHUB_WORKSPACE/docs/mkdocs.yml" \+ --output "$GITHUB_WORKSPACE/release-site" \+ --version "$VERSION" \+ --artifact "$GITHUB_WORKSPACE"/release-wheel/*.whl \+ --package-source workflow-wheel+ - name: Check out documentation deployment+ if: steps.publishable.outputs.publish == 'true'+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0+ with:+ repository: krypticmouse/dspy-docs+ ref: master+ path: docs-deployment+ persist-credentials: false+ token: ${{ secrets.GH_PAT }} # zizmor: ignore[secrets-outside-env]+ - name: Publish immutable release documentation+ if: steps.publishable.outputs.publish == 'true'+ env:+ GH_TOKEN: ${{ secrets.GH_PAT }}+ VERSION: ${{ needs.extract-tag.outputs.version }}+ run: |+ gh auth setup-git+ git -C docs-deployment config user.name github-actions+ git -C docs-deployment config user.email [email protected]+ aliases=()+ if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then+ aliases=(--alias "${VERSION%.*}")+ fi+ for attempt in 1 2 3; do+ git -C docs-deployment fetch origin master+ git -C docs-deployment reset --hard origin/master+ python docs/scripts/publish_versioned_docs.py \+ --repository docs-deployment \+ --site release-site \+ --identifier "$VERSION" \+ "${aliases[@]}" \+ --package-source workflow-wheel \+ --branch master \+ --require-current-renderer zensical+ if git -C docs-deployment push origin master; then+ exit 0+ fi+ sleep $((2 ** attempt + RANDOM % 5))+ done+ echo "::error::Documentation deployment changed repeatedly; rerun this release job"+ exit 1+open-main-version-bump-pr:needs: [extract-tag, build-and-publish-pypi]if: github.repository_owner == 'stanfordnlp'diff --git a/.github/workflows/docs-push.yml b/.github/workflows/docs-push.ymlindex ff6420ef0..61c239845 100644--- a/.github/workflows/docs-push.yml+++ b/.github/workflows/docs-push.yml@@ -155,10 +155,20 @@ jobs:gh auth setup-gitgit -C docs-deployment config user.name github-actionsgit -C docs-deployment config user.email [email protected]- python docs/scripts/publish_versioned_docs.py \- --repository docs-deployment \- --site current-site \- --identifier current \- --package-source working-tree \- --branch master- git -C docs-deployment push origin master+ for attempt in 1 2 3; do+ git -C docs-deployment fetch origin master+ git -C docs-deployment reset --hard origin/master+ python docs/scripts/publish_versioned_docs.py \+ --repository docs-deployment \+ --site current-site \+ --identifier current \+ --package-source working-tree \+ --branch master \+ --require-current-renderer zensical+ if git -C docs-deployment push origin master; then+ exit 0+ fi+ sleep $((2 ** attempt + RANDOM % 5))+ done+ echo "::error::Documentation deployment changed repeatedly; rerun this workflow"+ exit 1diff --git a/docs/scripts/build_docs.py b/docs/scripts/build_docs.pyindex 65434875a..fd527958b 100644--- a/docs/scripts/build_docs.py+++ b/docs/scripts/build_docs.py@@ -15,9 +15,9 @@ import tempfilefrom pathlib import Pathif __package__:- from .zensical_build import build_zensical_site+ from .zensical_build import HeadParser, build_zensical_siteelse: # Direct script execution from the deployed docs repository.- from zensical_build import build_zensical_site+ from zensical_build import HeadParser, build_zensical_siteRELEASE_VERSION = re.compile(@@ -166,8 +166,10 @@ def validate_release_site(site: Path, config: Path, version: str) -> None:raise RuntimeError(f"release site is missing required output: {', '.join(missing)}")home = (site / "index.html").read_text()- canonical = f'<link rel="canonical" href="https://dspy.ai/{version}/">'- if canonical not in home:+ metadata = HeadParser()+ metadata.feed(home)+ canonical = f"https://dspy.ai/{version}/"+ if metadata.metadata.get("canonical") != canonical:raise RuntimeError(f"release home page is missing canonical URL {canonical}")docs_dir = config.parent / "docs"@@ -184,7 +186,7 @@ def validate_release_site(site: Path, config: Path, version: str) -> None:raise RuntimeError(f"notebooks were not rendered: {', '.join(missing_notebooks)}")cards = site / "assets" / "images" / "social-zensical"- if not cards.exists() or not any(cards.rglob("*.png")) or 'property="og:image"' not in home:+ if not cards.exists() or not any(cards.rglob("*.png")) or "og:image" not in metadata.metadata:raise RuntimeError("social cards or Open Graph metadata were not generated")try:diff --git a/docs/scripts/publish_versioned_docs.py b/docs/scripts/publish_versioned_docs.pyindex 036bbd7f6..384127b4e 100644--- a/docs/scripts/publish_versioned_docs.py+++ b/docs/scripts/publish_versioned_docs.py@@ -14,6 +14,7 @@ from html import escapefrom pathlib import PathRELEASE_VERSION = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:(a|b|rc)(\d+))?$")+STABLE_VERSION = re.compile(r"^\d+\.\d+\.\d+$")DEFAULT_BRANCH = "versioned-docs"LEGACY_REDIRECTS_MANIFEST = ".dspy-legacy-redirects.json"HOST_CONFIG = (@@ -68,7 +69,11 @@ def working_directory(path: Path):def tree_digest(root: Path) -> str:digest = hashlib.sha256()- for path in sorted(item for item in root.rglob("*") if item.is_file()):+ paths = sorted(+ (item for item in root.rglob("*") if item.is_file()),+ key=lambda item: item.relative_to(root).as_posix(),+ )+ for path in paths:digest.update(path.relative_to(root).as_posix().encode())digest.update(path.read_bytes())return digest.hexdigest()@@ -102,6 +107,31 @@ def branch_file(repository: Path, branch: str, path: str) -> str | None:return result.stdout if result.returncode == 0 else None+def require_current_renderer(repository: Path, branch: str, renderer: str) -> None:+ inventory_text = branch_file(repository, branch, "versions.json")+ inventory = json.loads(inventory_text) if inventory_text else []+ current = next((entry for entry in inventory if entry.get("version") == "current"), None)+ actual = current.get("properties", {}).get("renderer") if current else None+ if actual != renderer:+ raise RuntimeError(f"production Current renderer is {actual!r}, expected {renderer!r}")+++def monotonic_aliases(repository: Path, branch: str, identifier: str, aliases: list[str]) -> list[str]:+ """Do not let a delayed older patch move a minor alias backward."""+ inventory_text = branch_file(repository, branch, "versions.json")+ if not inventory_text:+ return aliases+ requested = version_tuple(identifier)+ inventory = json.loads(inventory_text)+ holders = {+ alias: version_tuple(entry["version"])+ for entry in inventory+ if STABLE_VERSION.fullmatch(entry["version"])+ for alias in entry.get("aliases", [])+ }+ return [alias for alias in aliases if alias not in holders or holders[alias] <= requested]++def redirect_document(target: str) -> str:encoded = json.dumps(target)escaped = escape(target, quote=True)@@ -159,14 +189,18 @@ def publish_site(aliases: list[str],package_source: str,branch: str = DEFAULT_BRANCH,+ required_current_renderer: str | None = None,) -> bool:from mike import commands, git_utils+ if required_current_renderer:+ require_current_renderer(repository, branch, required_current_renderer)current = identifier == "current"if not current:# Automated publication is append-only. Intentional corrections to an# existing snapshot go through review in the deployment repository.version_tuple(identifier)+ aliases = monotonic_aliases(repository, branch, identifier, aliases)deployed = deployed_tree_digest(repository, branch, identifier)if deployed:if deployed != tree_digest(site):@@ -215,6 +249,7 @@ def main() -> None:required=True,)parser.add_argument("--branch", default=DEFAULT_BRANCH)+ parser.add_argument("--require-current-renderer")args = parser.parse_args()changed = publish_site(repository=args.repository.resolve(),@@ -223,6 +258,7 @@ def main() -> None:aliases=args.alias,package_source=args.package_source,branch=args.branch,+ required_current_renderer=args.require_current_renderer,)print("published" if changed else "already published")diff --git a/docs/versioning/README.md b/docs/versioning/README.mdindex 82fa5c1b6..27374d97b 100644--- a/docs/versioning/README.md+++ b/docs/versioning/README.md@@ -5,8 +5,8 @@ DSPy's versioned documentation is one static site managed by- `/` redirects to `/current/`.- `/current/` is the mutable documentation built from `main`.-- `/X.Y.Z/` and `/X.Y.ZbN/` are release snapshots built from their tags while importing the- exact released DSPy wheel.+- `/X.Y.Z/` and prerelease paths such as `/X.Y.ZbN/` are snapshots built from+ their tags while importing the exact released DSPy wheel.- `/X.Y/` redirects to the newest imported patch in that minor line.The picker lists Current and every stable or prerelease snapshot. Prereleases@@ -34,6 +34,26 @@ redirect pages such as `/api/` → `/current/api/`, and each build scopeshand-authored root-relative links to its own version so an old page cannotsilently jump into Current. Query strings and fragments survive redirects.+## Production publication++Current publication follows the renderer state described above. Release+publication fails closed unless production's Mike metadata identifies Zensical+as the reviewed Current renderer.++After a stable or prerelease `dspy` wheel reaches PyPI, the release workflow+preserves that exact wheel, builds its versioned path from the tag, and+publishes it through Mike after the existing package release job succeeds.+Only stable releases advance `/X.Y/`. Release-tag jobs never use GitHub's lossy+pending-concurrency slot. Mutable Current keeps latest-wins serialization+because a newer `main` build includes the superseded commit. Deployment writes+retry optimistic Git pushes; every release rechecks the Zensical promotion+marker after refetching, and a delayed older patch cannot move an `/X.Y/` alias+backward.++Corrections and rollbacks use reviewed pull requests in the deployment+repository. Restore a known-good tree with a new commit rather than rewriting+production history.+## Historical fidelityVersions 3.0 through 3.3 use the documentation source and Materialdiff --git a/tests/docs/test_versioned_docs.py b/tests/docs/test_versioned_docs.pyindex 4fabd151f..3c73c42db 100644--- a/tests/docs/test_versioned_docs.py+++ b/tests/docs/test_versioned_docs.py@@ -13,8 +13,9 @@ from docs.scripts.build_docs import (remove_source_maps,scope_root_relative_urls,set_release_badge_version,+ validate_release_site,)-from docs.scripts.publish_versioned_docs import publish_site, version_tuple+from docs.scripts.publish_versioned_docs import publish_site, require_current_renderer, version_tuplerequires_mike = pytest.mark.skipif(importlib.util.find_spec("mike") is None, reason="Mike is a docs-only dependency")@@ -85,6 +86,27 @@ def test_release_config_enables_mike_and_scopes_urls(tmp_path):result.unlink()+def test_release_validation_accepts_zensical_minified_metadata(tmp_path, monkeypatch):+ site = tmp_path / "site"+ (site / "api").mkdir(parents=True)+ (site / "assets" / "images" / "social-zensical").mkdir(parents=True)+ (site / "index.html").write_text(+ "<html><head>"+ "<link rel=canonical href=https://dspy.ai/3.4.0b1/>"+ "<meta property=og:image content=https://dspy.ai/card.png>"+ "</head></html>"+ )+ (site / "api" / "index.html").write_text("API")+ (site / "search.json").write_text("{}")+ (site / "llms.txt").write_text("DSPy")+ (site / "assets" / "images" / "social-zensical" / "card.png").write_bytes(b"png")+ config = tmp_path / "mkdocs.yml"+ config.write_text("site_name: DSPy\n")+ monkeypatch.setattr("docs.scripts.build_docs.importlib.metadata.version", lambda package: "3.4.0b1")++ validate_release_site(site, config, "3.4.0b1")++def test_production_build_removes_source_maps(tmp_path):site = tmp_path / "site"assets = site / "assets"@@ -184,10 +206,36 @@ def test_mike_preserves_patches_and_moves_minor_redirect(tmp_path):assert inventory[1]["aliases"] == []+@requires_mike+def test_delayed_older_patch_does_not_move_minor_redirect_backward(tmp_path):+ repository = make_repository(tmp_path)+ newest = make_site(tmp_path / "newest", "3.0.1")+ delayed = make_site(tmp_path / "delayed", "3.0.0")++ for version, site in (("3.0.1", newest), ("3.0.0", delayed)):+ publish_site(+ repository=repository,+ site=site,+ identifier=version,+ aliases=["3.0"],+ package_source="workflow-wheel",+ )++ alias = branch_file(repository, "versioned-docs", "3.0/guide/index.html")+ assert "../../3.0.1/guide/" in alias+ inventory = json.loads(branch_file(repository, "versioned-docs", "versions.json"))+ aliases = {entry["version"]: entry["aliases"] for entry in inventory}+ assert aliases == {"3.0.0": [], "3.0.1": ["3.0"]}++@requires_mikedef test_mike_refuses_to_replace_an_immutable_snapshot(tmp_path):repository = make_repository(tmp_path)site = make_site(tmp_path / "first", "original")+ for path in ("diving-deeper/tools", "diving-deeper/tools-react-and-mcp"):+ page = site / path+ page.mkdir(parents=True)+ (page / "index.html").write_text(path)arguments = {"repository": repository,"site": site,@@ -243,6 +291,9 @@ def test_mike_current_is_mutable_and_default(tmp_path):["git", "cat-file", "-e", "master:versions.json"], cwd=repository, capture_output=True)assert production_inventory.returncode != 0+ require_current_renderer(repository, "versioned-docs", "zensical")+ with pytest.raises(RuntimeError, match="expected 'material'"):+ require_current_renderer(repository, "versioned-docs", "material")@requires_mike