API Reference

Set once a capturing root is installed in this process, so a second install declines.

Abstract base for the agent / MCP backend: its emit_* methods are defined on AgentBase, so a custom theme struct MyAgent <: AgentBase end inherits the serializer and overrides only the dispatch points it wants (e.g. emit_figure(::MyAgent, …) to add a field to the JSON).

Agent / MCP backend — emit the document as structured data (agent.json + agent.md).

A bibliography entry reduced to the fields the gallery renders.

Build state of the implicit global document (current part/page/section).

A single PASS/FAIL check (a @expect) — one assertion of a computed value against a reference, the atom of a @benchmark test set. delta is the resolved deviation (relative or absolute per kind), pass is delta <= tol. Renders to a row of the gallery's fixed test-report, a LaTeX tabular row, and a native-typed JSON object in agent.json (the machine-readable verdict).

A code-snippet artifact — the source (and optionally its captured output), a sibling to Figure / Table. Renders as a highlighted <pre><code> block (gallery), an lstlisting-style verbatim (LaTeX), and a {kind:"code", source, output, lang} object (agent.json). This is how a report shows the COMPUTATION behind a figure or check — "here is the code, here is what it produced" (@code, a Documenter @example-like block, issue #69's recorded follow-up).

One comment turn: who wrote it and the markdown body.

Markdown + LaTeX source (unrendered; the theme draws it).

One diagnostic. item is the anchor of the related page/section/figure.

error/warning entries collected during render (-> diagnostics page, notes 09).

Document settings (analogous to TeX \documentclass + preamble).

Implicit top level (the catalogue). Order = tree position; numbers are not stored (numbering is the theme's job).

State threaded through the gallery emit functions for one render.

Lightweight handle pointing at a figure (used by thumbnails, etc.).

A single figure (placeholder). gen is deferred; code is the expression source for change detection (notes 10).

Abstract base for the default HTML gallery. Its rendering methods (emit_document, emit_section, emit_view, emit_figure, …) are defined on GalleryBase, so a custom theme struct MyTheme <: GalleryBase end inherits the whole gallery and overrides only the dispatch points it cares about (e.g. just emit_figure(::MyTheme, …)).

The default theme: a self-contained, interactive HTML gallery.

Abstract base for the LaTeX theme: its emit_* methods are defined on LaTeXBase, so a custom theme struct MyTeX <: LaTeXBase end inherits the whole LaTeX renderer and overrides only the dispatch points it wants (e.g. emit_figure(::MyTeX, …)).

LaTeX/PDF theme — emit a compilable .tex from the doc tree.

A page = one standalone HTML file (the unit of pagination). It groups in-page Sections and/or carries its own figures directly (page-as-leaf: a @page with figures and no @section). Pages are optionally grouped into a @part (a navigation grouping, not a file) named by part.

Per-render cache state: the previous manifest (read from disk) and the one being built. vault (if set) lets the cache key track the figure's DataVault data, not just its code+params.

A section (a group of figures + a description).

Diagnostic severity (notes 09).

A table artifact — structured tabular data, a sibling to Figure. Renders as an HTML/LaTeX table for humans and as structured rows for the agent backend. Inherently LLM-legible (it is already data).

Default numbering function: Sec. N / Fig. N / (N) for equations. Override it in the preamble with @pinaxsetup numberer = (kind, c) -> …, where kind is :section, :figure, or :equation and c is (; page, page_id, section, figure, subfigure, equation) — page is the 1-based page index and page_id its id (Symbol), so a numberer can prefix per "part" (e.g. c.page_id === :eq ? "EQ$(c.section)" : "GQ$(c.section)", usually with numbering=:page); section is the current section number, figure the document-wide figure count, subfigure the figure's index within its section (for hierarchical schemes like Fig. 2.3), and equation the document-wide equation count.

_figure_table(x) -> table | nothing

Extract a backend figure's plotted data for the agent backend's text/CSV view — an LLM reasons over numbers far more cheaply and precisely than over pixels. Returns nothing when the data is not introspectable (a pre-made image path, or a plot the loaded extension can't read); plotting extensions specialize it. Return shape: (; xlabel, ylabel, series), each series (; label, x, y).

Write the new manifest and delete asset files the previous render produced but this one did not.

_ignore_current_testset!()

Mark the innermost enclosing testset as excluded from the document. Declared with no methods on purpose: the only method lives in PinaxTestExt, and it cannot be missing where it matters, since @pinaxignore is only ever reachable from inside a @testset — which means Test is loaded, which means the extension is too. (A fallback method HERE would be overwritten by the extension's, and method overwriting during precompilation is an error.)

_install_test_capture!()

Push a capturing root PinaxTestSet onto the (task-local) testset stack and register an atexit hook that renders/dumps it and sets the exit code — the Pkg.test-delegation half of test. The -L preamble the delegating Pinax.test() hands to Pkg.test calls this; the method lives in PinaxTestExt (needs Test). Returns whether it installed — it declines during precompilation and when a capture is already open.

_materialize(fig, base, fmts) -> Vector{String}

Call the deferred fig.gen exactly once to produce the figure, write the assets, and return their paths (notes 02 pass 3). Figure objects are saved per fmt via pinax_save; an existing file path is copied (the file must exist when gen() returns).

_push_auto_code!(container, blk) -> CodeBlock | nothing

Place an auto-captured @code artifact into a container, at most once per id. Deduplication by id is what collapses a sweep's N samples — and N shards' dumps — onto the one block they share.

_resolve_theme(spec) -> Theme

Resolve a theme spec to a Theme: a Theme instance is returned as-is; a Symbol is looked up in the registry; an AbstractString is treated as a path to a .jl file that must evaluate to a Theme.

_save_with(saver, obj, base, fmt) -> path

Helper for backend extensions. Builds the destination path base.<fmt>, ensures its directory exists, runs saver(obj, dest) — the contract is (obj, dest): figure first, path second — verifies a file was actually written, and returns it.

_test_code_block(file, line) -> CodeBlock | nothing

The @code artifact for the assertion at file:line — the code that produced it. The id is derived from the line span, so every sample of a @testset for (the same line, N iterations) maps to ONE block: the sweep shows its specification once, not once per point.

_verbatim_code(file, line, expr) -> String | nothing

The source of an @code block's expression as written at file:line, rather than deparsed from the AST — @code f(x) = sum(k -> g(k), 1:x) should read back as itself, not as the begin-blocked normal form string(::Expr) produces. The statement's text is read from the file and the leading @code (with its keywords) is peeled off by trying each token boundary of the first line until the remainder parses to the very expression the macro was handed. nothing when the file is not readable (a REPL, a Documenter @example), where the deparsed form is all there is.

add_comment(path, id, text; author="") -> path

Append one comment turn for id to the TOML at path (created if absent), preserving existing turns and bookmarks. This is the CLI / LLM-loop write path: julia -e 'using Pinax; Pinax.add_comment("comments.toml", :eq_energy, "…"; author="llm")'.

capture_requested() -> Bool

Whether the environment asked for a test report at all: PINAX_TEST_OUT or PINAX_TEST_DUMP present. Presence is the request — report_out has a default, so no particular value can be one — which is what lets install_test_capture! sit in a committed runtests.jl.

completeness_overview(c) -> Function

The overview content for a TestShards completeness verdict — pass it as overview to render_test_report:

c = TestShards.completeness(windows, ran)
render_test_report(dumps; out = "test-report", overview = completeness_overview(c))

A sharded report that is missing a shard looks exactly like a smaller suite, and nothing in the artifact contradicts that reading. This puts the verdict IN the artifact: the numbers as a table (native rows in agent.json, so a registry or an agent reads them) and the verdict — with the positions of any hole — as prose above it.

Declared here with no methods: the one method lives in PinaxTestShardsExt, because it takes TestShards' Completeness. TestShards.completeness_report renders the same verdict for a CI job summary; this renders it for the document, and the two surfaces are deliberately separate.

contents(entries; out, title="Contents", level=:cards) -> path

Render a standalone meta-index linking to several separately rendered galleries, and return the written index.html path. Use it to put a customizable "map of contents" one level above galleries that were each produced by their own render call.

Each entry is a NamedTuple describing one target gallery:

level mirrors the gallery index verbosity: :toc (link list), :cards (thumbnail cards, default), :rich (cards + each entry's items). Hrefs and thumbnails are emitted verbatim, so give paths relative to the generated index.html (or absolute URLs); this neither renders the galleries nor copies their assets — the targets are expected to already exist.

Pinax.contents(
    [
        (; title="Thermal", href="thermal/index.html",
           summary="Equilibrium TPQ", thumbnail="thermal/assets/figures/cv.svg"),
        (; title="Quench", href="quench/index.html", summary="Global-quench dynamics"),
    ];
    out="site", title="Project Atlas",
)

Build a scoped document: doc = document() do … end (for test isolation).

documenter_downloads(res, format::Documenter.HTML; page, ext="pdf", label=basename, heading="")
    -> String

An @raw html block of download links to a staged gallery's asset files — by default its PDFs — for a Documenter page. res is the NamedTuple from documenter_gallery / documenter_stage; each matching asset (identified via rendered_assets(res.dir)) becomes an <a download> whose URL is resolved against the embedding page using format.prettyurls (so it is correct under either setting). label maps an asset path to its link text; heading is an optional bold lead line. Empty string if the gallery has no matching asset. Requires using Documenter.

documenter_embed(url; height=nothing, min_height=420, title="Pinax gallery",
                 id=nothing, new_tab=true, style="") -> String
documenter_embed(url, format::Documenter.HTML; page, kwargs...) -> String

Return a Documenter $@raw html$ block that embeds a rendered, self-contained Pinax gallery — its entry HTML at url — as an auto-resizing, same-origin <iframe>: the loose Pinax → Documenter bridge (roadmap 07; not a Documenter plugin). Drop the returned string into a Documenter markdown page (or a Literate @raw html postprocess) and the Pinax page renders as-is inside the Documenter site — iframe isolation keeps the gallery's body/h1/nav/figure CSS and its KaTeX + interactive JS from colliding with Documenter's, and the iframe grows to its content (no inner scrollbar), re-fitting on in-gallery navigation and after KaTeX/image layout.

• url is the gallery's index.html (or a single <page>.html) relative to the built Documenter page — e.g. "../gallery/" for a top-level page under prettyurls.
• The 2-arg format::Documenter.HTML form takes url relative to the site root plus the page's src-relative .md path page=, and derives the correct ../ prefix from format.prettyurls, so you write the path once and it stays correct under either prettyurls setting.

Requires using Documenter (the bridge is a package extension). Render the gallery with render/report as usual — this only wraps its URL; it neither computes nor moves the gallery.

documenter_gallery(jl; out, src, workdir=dirname(jl), prepare=nothing, theme=:gallery,
                   format=nothing, page="", reset=true, kwargs...) -> (; dir, siteroot, embed)

The source-seam bridge: hand it a Pinax manuscript .jl (the pre-render script — @page/@section/@figure/@desc/…) and it RUNS the script at docs-build time (in a throwaway module, with workdir as the working directory so the manuscript's relative figure paths and data resolve), renders the resulting gallery into out under the Documenter source src — so makedocs copies it verbatim into the deployed site — and returns the wiring for one call from .jl to a deployed Documenter page.

Returns (; dir, siteroot, embed): dir is the rendered gallery directory (joinpath(src, out)), siteroot its site-root URL ("out/"), and embed an @raw html iframe block for it (empty unless BOTH format::Documenter.HTML and the embedding page's src-relative page are given, which make the url prettyurls-correct). Pass embed into a Documenter page (or documenter_embed yourself off siteroot). Extra kwargs forward to documenter_embed (title, height, min_height, …).

prepare is a zero-arg callback run BEFORE the manuscript — the seam for the figure workaround: a deploy env (CI) has no access to figures/data that live only on your machine, so stage them here (fetch a release/branch/artifact, copy committed assets into workdir, …). Computed figures (@figure plot(...)) simply recompute; only local-only files/data need prepare. reset=true gives the manuscript a fresh implicit document; the manuscript need not call render — this does.

Requires using Documenter.

documenter_stage(gallery; src, out, format=nothing, page="", clean=true, kwargs...)
    -> (; dir, siteroot, embed, assets)

Carry an already-rendered Pinax gallery gallery (an out= directory from a prior render / report) into the Documenter source tree at joinpath(src, out), so makedocs copies it — and all its assets, PDFs included — into the deployed site. This is the bundling path for the common reality that Pinax + DataVault outputs live in gitignore'd local directories: render locally where the data is, then documenter_stage the result into the docs at build time (no commit of the raw outputs needed).

Returns the same wiring as documenter_gallery — (; dir, siteroot, embed, assets) — where assets is rendered_assets(dir) (the identified output paths). clean=true replaces any existing dir. Requires using Documenter.

dump_test_report(root::TestNode, path) -> path

Write a testset tree to path as TOML, to be merged and rendered later by render_test_report. This is what a CI shard emits instead of rendering its own partial gallery.

Render one @expect check (a gallery <tr>, a LaTeX tabular row, or a JSON check object). emit_check(theme, check, ctx).

Render one @code block (source + captured output). emit_code(theme, codeblock, ctx).

Render a node's id-keyed comments inline. emit_comments(theme, anchor, ctx).

Emit the doc tree (also pass 3: materialize + draw). A single @page renders to one self-contained index.html; multiple @pages render to one file per page (<page>.html) plus an index.html of thumbnail cards linking to them (notes 02/06).

emit_document(theme, doc, outdir, cache; comments_file) -> path

Render doc into outdir and return the entry-file path. This is the one method every theme must implement; render dispatches here on the resolved theme.

Render one figure — its assets, caption and co-located comments. emit_figure(theme, figure, ctx).

Render the multi-page index of pages. emit_index(theme, doc, io, outdir, bookmarks).

Render one page's body (its page-level content + in-page sections). emit_page(theme, page, ctx).

Render one section into the theme's output stream. emit_section(theme, section, page, ctx).

Render one table artifact (an HTML/LaTeX table, or a JSON object with native-typed rows). emit_table(theme, table, ctx).

Render a markdown+math source (a @desc/@caption). emit_text(theme, source, item, ctx; block).

emit_view(theme, ::Val{view}, figs, assetdir, layout, ctx)

Render a unit's figures in the named view. The default view is :grid; add a method on ::Val{:graph} / ::Val{:table} (etc.) to introduce a new per-unit presentation.

install_test_capture!() -> Bool

Install the capturing root from inside the suite, so a report comes out of a plain Pkg.test() — whoever owns that call keeps owning it, along with the sandbox, the coverage flags and everything else it sets.

test reaches the same installer through a -L preamble, which is what lets it leave runtests.jl untouched. That route is not always open: a CI action that owns the Pkg.test call exposes no way to add -L — julia-actions/julia-runtest has no such input — and replacing it to get one costs whatever else it was setting, coverage included. This is the other way in, and it composes with anything that can set an environment variable.

using MyPackage, Test, Pinax
Pinax.install_test_capture!()
@testset "MyPackage" begin
    include("a.jl")
end

It does nothing unless the environment asked — see capture_requested. So the line can be committed and a developer's Pkg.test() behaves exactly as it did; CI turns it on by setting PINAX_TEST_OUT or, per shard, PINAX_TEST_DUMP.

It is also idempotent. Called when a capture is already open — under test, whose preamble installed one before the suite was even read — it declines. A second root would take every assertion and leave the first to render an empty and green report, which is the exact failure this seam exists to prevent.

Is x a backend figure object? Defaults to false (Plots/Makie ext overrides).

load_test_dump(path) -> TestNode

Read back a tree written by dump_test_report.

materialize!(fig, base, fmts, cache) -> :hit | :miss

Populate fig.assets. On a cache hit (unchanged key + assets still present) the deferred gen is NOT called. On a miss, materialize for real and record the result in the new manifest. May rethrow whatever _materialize throws (the caller turns it into a diagnostic).

pinax_save(x, base, fmt) -> path

Save the figure object x to base (an extensionless base path) in fmt (:svg/:pdf/…) and return the actual path. Per-backend implementations are injected via package extensions (weakdeps) (notes 04).

read_comments(path) -> (comments, bookmarks)

Read an id-keyed comments TOML. Returns comments::Dict{Symbol,Vector{Comment}} (id -> turns, in file order) and bookmarks::Set{Symbol}. A missing or unparseable file yields empties (non-fatal).

Register theme under name so it can be selected with @pinaxsetup theme=name / render(theme=name).

render([doc]; out, theme=GalleryTheme(), force=false) -> path

Render the catalogue: structure (pass 1, done by macros) -> resolve (pass 2) -> materialize + emit (pass 3, theme). Writes into the out directory and returns the path of the generated entry file. doc defaults to the implicit global document. force=true re-materializes every figure, ignoring the cache (notes 10).

comments_file is the id-keyed annotation store read and shown inline by the gallery (default out/comments.toml). render only READS it — it persists across renders and is written by the CLI / browser export / LLM loop, never overwritten here.

theme selects the renderer: a Theme instance, a registered Symbol, or a path to a user theme file (see theme.jl). nothing (default) uses the document's @pinaxsetup theme=….

vault is an optional DataVault.Vault (notes 10; needs using DataVault, which loads the PinaxDataVaultExt extension): when given, (1) the cache key tracks each params::DataKey figure's data via its .done marker, so recomputing the data re-materializes the figure (not just code/param changes), and (2) figure provenance is recorded with DataVault.record_figure under study (defaults to the vault's run).

render_test_report(root::TestNode; out, title="Test report", page_when=…) -> (; gallery, agent)
render_test_report(dumps::AbstractVector{<:AbstractString}; out, …)       -> (; gallery, agent)

Render a testset tree as a Pinax document: an overview page (one row per test file, ranked by worst margin), then one status=:benchmark page per file whose sections mirror the nested testsets, each with its margin figure.

Given a list of TOML dumps (see dump_test_report) their trees are merged under one root first — which is how a sharded CI run becomes a single coherent gallery instead of N disconnected ones.

overview is an optional zero-argument function run with the overview page open, so it writes with Pinax's ordinary content macros — @desc, @table, @raw — and its content lands there. This is how something the running job knows but the tree does not gets into the artifact instead of into a CI log that expires: a completeness verdict ("every unit ran exactly once"), the environment, a note about what was skipped. A @desc appears above the fixed tables. If the hook throws, that is a diagnostic in the report, not a failed render.

Writes <out>_html (the human gallery) and <out>_agent (agent.json), following the same convention as report.

render_test_report(dumps; out="test-report", overview = () -> begin
    @desc md"**Every unit ran exactly once** — 24 observed, 24 run."
    @table (; metric=["units observed", "units run"], value=[24, 24]) caption = "Completeness"
end)

rendered_assets(dir; ext=nothing, absolute=false) -> Vector{String}

The output asset files a Pinax render produced under dir, read from its .pinax-manifest.toml (every @figure/@table output — svg/pdf/png/gif/csv). Paths are relative to dir (or absolute with absolute=true), sorted and de-duplicated. ext filters by file extension — ext="pdf" returns just the PDF outputs, the "identify the output pdf paths" query for bundling a rendered gallery into a deploy (e.g. Documenter). Returns String[] when dir has no manifest (nothing rendered there yet) — never errors.

This reads what a previous render(; out=dir) recorded; it does not itself render.

report(vault, recipe; title, out, study=nothing, kwargs...) -> (; gallery, agent, n)

Bridge a DataVault vault to rendered artifacts. Discovers the vault's completed keys, loads each result Dict, hands the (key, dict) pairs to the project-supplied recipe (which builds the doc with @page/@figure/@table), then renders the human gallery and the agent.json with the vault wired in (data-fingerprint cache tracking + provenance). The driver — discover, load, render, lineage — is project-independent; only recipe is project-specific. Requires using DataVault (which also loads ParamIO); the core method errors with a hint when the extension is not loaded.

Where a shard writes its tree instead of rendering (PINAX_TEST_DUMP); empty = render directly.

The CI matrix cell this run belongs to (PINAX_TEST_MATRIX, e.g. "julia 1.11 · ubuntu"); empty = not a matrix run. Set by the CI job; carried into the dump so a later merge can group cells (issue #69 K).

Where the test report is written (PINAX_TEST_OUT, default test-report) → <out>_html + <out>_agent.

Report title (PINAX_TEST_TITLE, default Test report) — the document title + overview heading.

Reset the implicit document (fresh, empty). The preamble @pinaxsetup calls this.

resolve!(doc) -> doc

pass 2 (structure only, no numbers). Builds the label->node table. Numbers are assigned by the theme (CSS), so none are emitted here. Facet expansion and full diagnostic collection come in later slices.

Resolve a page's main figure: explicit @thumbnail > thumbnail=true marker > top (first) figure (notes 02).

serve(dir="out"; host="localhost", port=8000, blocking=true) -> nothing | handle

Serve the rendered gallery in dir over HTTP so you can open the printed link in a browser. Picks the next free port from port if it is busy. Blocks until interrupted (Ctrl-C); with blocking=false it returns (; server, url, port, task) and you close(handle.server) to stop.

set_bookmark!(path, id, on=true) -> path

Mark/unmark id as bookmarked in the TOML at path.

sweep_mean(pairs, quantity, axis) -> (xs, means)

Helper for report recipes: the mean of a scalar quantity in each result Dict, grouped by the swept dotted param axis (e.g. "system.r"). The generic "scalar vs swept parameter" reduction, useful for any sweep; the plot and labels stay the recipe's job. Pure; needs no DataVault.

Pinax.test([runtests]; out="test-report", title="Test report", dump="") -> nothing

Run a test suite and render it as a Pinax document — the interface that outputs a testset directly. There is no Pinax-specific macro in the suite: it stays plain @testset / @test. The only Pinax touch is the call. Two forms:

• Pinax.test() — test the active package. Delegates to an unmodified Pkg.test, passing a -L preamble that installs a capturing root before the suite runs (so its @testset tree is captured) and renders at exit. Pkg.test still does all the sandbox / dependency work; a bare Pkg.test() without this installs no root and produces no report.
• Pinax.test(runtests::AbstractString) — render a specific test file in the current process (no sandbox): open a capturing root testset, include the file, render.

Each test file (a .jl-named @testset) becomes a status = :benchmark page, each nested @testset a section, each @test a Check carrying its real got/want/tol — and, by default, a @code block holding the source that produced it, so a reader sees what was measured and not only whether it passed. Writes <out>_html + <out>_agent; with dump set, dumps the tree there instead (a sharded CI shard) for render_test_report to merge later. A red suite still fails the process — the report never changes the verdict. A suite may also draw (@desc/@figure/@table/…); that content is captured, and is a no-op under a bare Pkg.test().

The test() delegation is Test-free (only Pkg, a stdlib); the in-process test(runtests) form lives in PinaxTestExt and needs Test loaded.

A benchmark / test-set page. @benchmark :id "Title" [summary=…] [layout=…] begin … end — a @page whose status is fixed to :benchmark, holding @expect checks (plus any @page content: @desc/@figure/@table/@section — a @section's @expects count toward the verdict too). Each backend dispatches on the :benchmark status to render a verdict: a machine-readable benchmark block in agent.json, a fixed-layout test-report in the gallery, and a tabular + verdict line in LaTeX. Mirrors @page (it IS a page); @expect populates the page's checks.

Declare the .bib source(s) used to resolve @cite. @bibliography "refs/a.bib" …

Name the preceding item (like \caption), overwriting any caption/label set before it:

• after a @figure → the figure's caption;
• after a @test / @expect → the check's quantity name (its label). This is how a swept @testset for names the quantity a convergence figure plots — @test isapprox(E, oracle; rtol=…) followed by @caption "energy" titles the check (and its convergence figure) energy instead of the raw expression (issue #69 C). Grouping is by this label, so every iteration's @caption folds the sweep into one named quantity.

@code [caption=…] [id=…] [lang="julia"] [run=true] expr
@code [kw…] begin … end

Show a code snippet — the computation behind a figure or check — and, by default, RUN it and show its result. @code E = compute(χ) renders the source E = compute(χ) and its value; the assignment still happens in the enclosing scope, so following code (a @test, a @figure) uses E. run=false shows the source only (no evaluation). It captures the block's return value (not stdout).

The snippet is the source as written — read back from the file, so comments and formatting survive and a definition does not come back as a begin-blocked normal form. (Where there is no readable source file — a REPL, a Documenter @example — it falls back to deparsing the expression.)

Inside a test, every @test already gets one of these automatically, holding the code that produced it; an explicit @code is for showing a computation deliberately (a definition above a sweep, say).

Content, not structure (law II): it needs using Pinax, is purely additive, and has no bearing on a verdict — a Documenter @example-like block, rendered as code + output by every backend.

Diagnostics mode. @debug_mode true

Section description (markdown + LaTeX source). @desc md"…"

Register one PASS/FAIL check — a @expect (the atom of a @benchmark test set). The first two macro arguments (id, label) are the check id (a Symbol, or a String coerced to one) and a human label; then got= (required) is the computed value, want= (default 0.0) the reference, tol= (required) the tolerance, and kind= (default :auto) selects the deviation: :rel (relative) when there is a nonzero reference, :abs (a residual against want=0). @expect "E1" "energy density e" got=e want=e_ref tol=1e-2.

The tolerance is relative by default with a nonzero want, absolute for a residual (want=0); kind=:rel with want=0 is an error, and a non-finite got/want or a non-positive tol is an error — a check is a trust gate, so an ill-posed assertion fails loudly rather than mis-reporting.

@expect is manuscript vocabulary (a @page/@benchmark/@section). Inside a test suite the assertion is @test — Pinax recovers its got/want/tol and shows the same margin — so @expect used directly in a @testset is an error, not a silently-unenforced check (issue #69 F).

Register a plot; the expression is DEFERRED. @figure expr [params=…] [caption=…] [id=…] [thumbnail=…] / @figure [kw] begin … end

Raw string (preserves $…$). Used by @desc md"…" etc.

Notation macro. @newcommand "\E" raw"\langle H\rangle"

This page contributes no main figure to the index.

A page. @page :id "Title" [summary=…] [layout=…] [status=…] begin … end

status tags the page's maturity so a backend or registry can treat trial and result differently: :final (default — the shaped/curated page) vs :trial (a raw experiment attempt). Pinax only carries the tag (any Symbol is accepted, e.g. :experimental/:draft); the agent backend exposes it as "status" for RAG/Archeion filtering and the gallery badges non-:final pages. A page inherits its enclosing @part's status default unless it sets its own.

A navigation group of pages (LaTeX \part). @part :id "Title" [desc=md"…"] begin … end — the pages declared inside belong to this part and are grouped (collapsibly) under it in the index and nav. desc= is an overview shown beneath the part heading on the index (what this whole group covers). A part is NOT a file; each @page (or top-level @section) inside it is still its own HTML page. status= sets a default maturity (e.g. :trial) that the part's pages inherit — so a whole "Trials / experiment log" group is declared once, the shaped result living in a separate part.

@pinaxignore

Drop the enclosing @testset — and everything under it — from the rendered document. The tests still RUN and still count toward pass/fail; they simply do not become a page or a section. For the noise you do not want in a report (a smoke check, an Aqua block, a slow fixture):

@testset "Aqua tests" begin
    @pinaxignore
    Aqua.test_all(MyPkg)
end

A no-op when the report is off, so it is safe to leave in the code permanently.

Document settings + reset of the implicit document. @pinaxsetup theme=… index=… numbering=… debug=…

Inject a raw block into the current section — the escape hatch for project-specific UI that markdown can't express (coverage tables, broken-data banners; notes 06 §6). @raw x evaluates x to a string and the theme emits it verbatim (the gallery as raw HTML; trusted author content): @raw raw"<table class=cov>…</table>". Use @desc for prose; @raw for hand-built markup.

A section. @section :id "Title" [by=…] [summary=…] [layout=…] begin … end

Register a table artifact — first-class tabular data (sibling to @figure). data may be a NamedTuple of columns (T=…, M=…), a Matrix (with header=), a Vector of NamedTuple rows, or a Vector of row-vectors/tuples (with header=). @table data [caption=…] [id=…] [header=…] [params=…].

Set the page main figure. @thumbnail :figid (priority: explicit @thumbnail > a thumbnail=true @figure > the top figure; notes 02 resolve).