DSPy: The framework for programming—not prompting—language models
Versioned documentation
DSPy's versioned documentation is one static site managed by Mike:
/redirects to/current/./current/is the mutable documentation built frommain./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
do not claim the stable minor alias. Minor aliases are navigation conveniences
and are hidden from the picker. Mike owns versions.json, the
default redirect, aliases, and version directories on the generated
master branch in krypticmouse/dspy-docs.
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
Current and release publication update production master in
krypticmouse/dspy-docs. Both paths require Mike metadata identifying Current
as Zensical before they write, so an unversioned or unexpected deployment fails
closed. Corrections use reviewed pull requests in that repository.
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
silently 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 fidelity
Versions 3.0 through 3.3 use the documentation source and Material
configuration from their release tags. Their requirements were not fully
pinned and referred to DSPy on the moving main branch. Bootstrap replaces
that dependency with the release wheel and resolves the remaining requirements
no later than the tag's commit time.
The tags' uv.lock files describe DSPy's project and development dependencies,
not the separate toolchain in docs/requirements.txt. They do not lock MkDocs,
Material, Jupyter, redirects, mkdocstrings, or llmstxt.
Each snapshot contains _meta/build.json with its source tag and commit,
renderer version, DSPy artifact source and SHA-256, complete resolved Python
package set, and known reconstruction differences.
PyPI never published dspy==3.1.1. That snapshot is the sole exception: its
wheel is built from tag 3.1.1 using the release workflow's metadata
substitutions and is marked tag-built-wheel.
The original generated deployments were not archived, so reconstructed HTML is not expected to be byte-identical. The compatibility contract is routes, redirects, anchors, content, notebooks, matching API symbols, search behavior, metadata, navigation, and user-facing interactions. The version selector, build metadata, and omitted source maps are intentional additions.
Historical corrections
Release snapshots are immutable to automation, not permanent write-once
storage. An identical retry is a no-op; a retry with different output fails
before Mike can replace /X.Y.Z/.
An intentional correction is a reviewed pull request directly against
krypticmouse/dspy-docs, normally limited to the affected version directory.
That repository's pull request and Git history provide audit and rollback.
Output size
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.