Maintaining documentation

Follow the development setup, then run:

just docs-serve  # preview at http://127.0.0.1:8000; Ctrl-C stops the server
just docs-build  # strict static build into site/
just check-docs  # check committed generated files, release notices, notebooks, and build

The docs commands install the locked docs dependency group through uv into .venv-docs/, separate from the active SDK test profile. They do not require scientific reader extras or live dataset access. Initial dependency installation needs network access; the content build reads local source and saved notebook outputs. Documentation checks are part of just check and CI's static job, once per run rather than once per reader profile.

Edit the source that owns the content

Run just docs after changing the registry, and commit its generated Markdown. These text artifacts keep the catalog usable on GitHub too. README and provider indexes are handwritten. Never add prose to generated pages.

The registry's catalog mapping connects each implemented dataset ID to a unique handwritten usage guide in docs/providers/. The site combines that guide and its generated catalog reference into one dataset page. Required summary, formats, selection, inputs, reader_extra, and examples describe the implemented fetch behavior. Keep file formats and selection explicit: a transport or capability flag cannot tell readers whether they receive whole files or subsets. Use reader_extra: null when fetching is supported but no bundled reader opens the format; adding a dataset does not require adding a reader. Links to the guide are redirected during assembly; GitHub readers use ordinary links between the two source files. Edit usage and scientific caveats in the guide, and facts in the registry. The generator checks missing guides, unknown IDs, and obsolete outputs. The generator does not create provider access notes: add those when introducing an agency, and link its catalog.

CLI and notebook previews are assembled into ignored .build/docs/. Zensical renders that tree into ignored site/, including API documentation through mkdocstrings. These directories are disposable build outputs. Root files and examples retain their repository paths in staging, except docs/index.md becomes the home page and the root README becomes project.md. The builder adjusts their relative Markdown links; source links still work on GitHub. Local links to notebooks become links to rendered pages, with a separate download link to the original notebook. Notebook cells are never executed during a build.

just docs-serve watches the maintained documents, notebooks, Python source, registry, and generation scripts. It refreshes staged files only when they change; Zensical rebuilds the preview. After editing generation scripts, restart the server so changed Python code is loaded. Run just docs before committing registry edits: the preview renders current data without changing committed generated files.

Navigation, links, and diagrams

Edit zensical.toml to change navigation outside the Datasets section. Dataset navigation is generated from stable IDs and validated catalog metadata into ignored .zensical.generated.toml; the empty Datasets section is its insertion point. Organize by reader task, and link additional provider catalogs and decisions from their indexes. Use relative Markdown links with explicit filenames so GitHub and the site can resolve them. Strict builds reject broken internal links and anchors. External URLs are not probed by this offline gate.

Keep Mermaid source in fenced mermaid blocks next to the explanation. Use it for relationships or sequences that are clearer visually, and check the actual browser rendering after changing a diagram; a successful Markdown build alone does not validate Mermaid syntax. Keep critical meaning in the surrounding prose.

For notebook updates, follow the example refresh workflow. Saved results describe their recorded executions, not current upstream health.

Releases and publication

The site currently describes the source checkout. Mark source-only features Unreleased and retain the changelog as the release history. Write user-facing release-note fragments; just release assembles them with Towncrier and regenerates registry documentation. The website does not own release policy.

Public hosting is selected work in the Now / Next / Later roadmap, tracked in issue #56 without a deadline or release assignment. The selected design uses Cloudflare Workers Static Assets: a small home page at usdata.dev and a Worker serving versioned docs from R2 at docs.usdata.dev, defaulting to the latest published package. Release references come from that release's code and registry; documentation-only corrections must retain that reference version and record their own revision. Start with the reviewed v0.10.0 documentation; earlier releases are outside the archive scope. For future releases, attach the validated built-docs archive to the GitHub release. The scheduled docs Worker imports that same build into R2 and advances the version catalog after verification. These website assets are separate from Python distributions. Preserve published versions and show the selector once two versions exist, as described in the roadmap. Retention does not imply ongoing maintenance of old package versions.

The ordinary local build still describes its checkout. Release archive builds isolate the tagged package source from the reviewed documentation revision. Website operations describes the independent home/docs Workers Builds projects, R2 binding, scheduled imports, validation, and rollback. Cloudflare manages authorization; no Cloudflare or R2 secret is required in GitHub. R2 dataset archives and website catalog browsing remain separate candidate work.