Developer docs

Working on EpiAware packages and this website.

Reference notes for developing EpiAware packages. Start with Contributing for the overall workflow, and each package’s own developer documentation for specifics.

Faster test runs

Quality checks (Aqua.jl, formatting, doctests) are the slowest part of a test run. Skip them while iterating:

julia --project=test test/runtests.jl skip_quality

Use Revise.jl so code changes take effect without restarting Julia.

Running only the tests you care about

Tests are written as @testitems, so they can be run by path or by tag with TestItemRunner.

using TestItemRunner

run_tests("test/censoring/")                  # one directory
run_tests(filter = ti -> (:unit in ti.tags))  # one tag

The VS Code Julia extension exposes the same test items in its test explorer.

Code quality

Packages run a consistent set of quality tools:

  • Aqua.jl for common package problems
  • JET.jl for static analysis (@report_opt, @report_package)
  • Doctests and formatting checks

EpiAwarePackageTools.jl provides the shared harnesses, including automatic-differentiation tests across backends.

Checking performance

Each package has a benchmark suite, and most publish a benchmark page in their docs showing which automatic-differentiation backends work, how fast they are, and where they fail.

julia --project=benchmark benchmark/runbenchmarks.jl

For a single function, BenchmarkTools is usually enough.

using BenchmarkTools
@benchmark cdf(d, 5.0)

Building documentation locally

Each package builds its own docs from docs/:

julia --project=docs docs/make.jl

Literate tutorials are the slow part of a docs build. Skip them for a quick check:

julia --project=docs docs/make.jl --skip-notebooks
SKIP_NOTEBOOKS=true julia --project=docs docs/make.jl   # same thing

This website

This site is built with Quarto. To preview locally, install Quarto and run:

quarto preview      # live preview
quarto render       # build the static site into _site/

Every push and pull request builds the site in CI, so a broken build is caught before merge. Pushes to main also deploy it to GitHub Pages. The workflow is in .github/workflows/publish.yml.

To add a package to the Packages list, add a row to the table in packages/index.qmd. Give the row a data-category so it picks up the category filter, link the package name to its documentation, and link the icon to its source.

When something breaks

Your changes are not taking effect. Load Revise before the package, or restart Julia.

“Package not found” while developing. Activate the right environment and instantiate it. If you are working on more than one EpiAware package at once, Pkg.develop the ones you are changing so the local copies are used rather than released versions.

Precompilation errors. Run ] resolve, then Pkg.precompile(). If it persists, delete Manifest.toml and ] instantiate to rebuild the environment.

More detail lives in each package’s own developer FAQ.

Releases

Releases are cut from main by tagging a version, following each package’s documented release process.