Skip to content

Maintaining the docs

The site is built with Zensical from the CFA zensical template. Everything under docs/ is Markdown that Zensical renders without Julia; two directories of it are generated by Julia and committed:

Output Source Generator
docs/api/ docstrings, selected by julia-docs/src/*.md julia-docs/make.jl (Documenter with the DocumenterMarkdown fork)
docs/examples/ Literate scripts in julia-docs/examples/ julia-docs/examples.jl (Literate, executed)

Do not edit the generated files by hand; pre-commit hooks skip them.

Commands

The commands are recipes in the root justfile. Regeneration uses Julia 1.13 (juliaup add 1.13 once); site builds use uv.

Task Command
Instantiate the Julia docs environment just docs-setup
Regenerate the API reference just docs-api
Run all examples, or some just docs-examples, just docs-examples inference_engines
Build the site strictly just docs-build
Preview locally just docs-serve

Drawing Petri nets in the examples needs the Graphviz dot executable on the PATH.

When to regenerate

  • Docstrings changed: run just docs-api and commit docs/api/. CI only builds the site from the committed Markdown, so it does not catch stale API pages.
  • Package behaviour or an example changed: run just docs-examples (or just the affected example) and commit docs/examples/. CI does not run the examples either, so an example broken by a package change only shows up when it is regenerated.

Adding an example

  1. Write a Literate script in julia-docs/examples/: # lines are Markdown, and the value of each code block's last expression is shown, with plots saved as images. End a block with nothing #hide to show no output.
  2. Seed every random number generator, including the rng of any filter constructed directly, so reruns reproduce.
  3. Add any new packages to julia-docs/Project.toml.
  4. Run just docs-examples <name>, add the page to the nav in zensical.toml, and check it with just docs-serve.

The site documents software. Examples use simulated data and should not present scientific results.

Deployment

.github/workflows/docs.yaml builds the site strictly on every pull request and deploys it to GitHub Pages on pushes to main.