Publishing

Document rendering for regulatory submissions, built on Quarto.

Document model

jamb.publish.document.build_publish_document(items, title, *, subtitle=None, include_links=True, document_order=None, graph=None)

Assemble a PublishDocument from requirement items.

Items are ordered by document hierarchy, then document prefix, then UID, and grouped into one section per prefix.

Parameters:

• items (list[Item]) – The items to publish.

• title (str) – The document title.

• subtitle (str | None) – Optional metadata line shown under the title.

• include_links (bool) – Whether to carry parent and child link references.

• document_order (list[str] | None) – Document prefixes in hierarchy order; used to sort sections. Prefixes outside the list sort last, alphabetically.

• graph (TraceabilityGraph | None) – The traceability graph, used to resolve child (reverse) links.

Returns:

PublishDocument – The assembled document.

Return type:

PublishDocument

class jamb.publish.document.PublishDocument

A complete document ready to be rendered to any output format.

title

The document title shown on the title block.

subtitle

Optional metadata line shown under the title (e.g. document id, version, date, status), or None to omit.

sections

Document sections in hierarchy order.

total_items

The number of items across all sections.

include_links

Whether parent and child link references render.

known_uids

Every UID in the document, used to decide whether a parent link renders as an anchor or as plain text.

__new__(**kwargs)

__init__(title, subtitle, sections, total_items, include_links, known_uids)

Parameters:

• title (str)

• subtitle (str | None)

• sections (tuple[RenderSection, ...])

• total_items (int)

• include_links (bool)

• known_uids (frozenset[str])

Return type:

None

class jamb.publish.document.RenderSection

A group of items sharing a document prefix.

__new__(**kwargs)

__init__(prefix, items)

Parameters:

• prefix (str)

• items (tuple[RenderItem, ...])

Return type:

None

class jamb.publish.document.RenderItem

A single requirement item prepared for rendering.

uid

The item identifier, used verbatim as its anchor.

type

The item type, which selects how the body is rendered.

heading_text

The text shown on the item’s heading line.

body

The item body text (empty string when the item has none).

level

Heading depth for heading items; None otherwise.

parent_links

UIDs this item traces up to.

child_links

UIDs that trace down to this item, restricted to the items present in the rendered set.

__new__(**kwargs)

__init__(uid, type, heading_text, body, level, parent_links, child_links)

Parameters:

• uid (str)

• type (Literal['requirement', 'info', 'heading'])

• heading_text (str)

• body (str)

• level (int | None)

• parent_links (tuple[str, ...])

• child_links (tuple[str, ...])

Return type:

None

Quarto source

jamb.publish.qmd.render_qmd(doc, fmt, *, theme=None, reference_doc=None, typst_header=None)

Render a publish document to .qmd source.

Parameters:

• doc (PublishDocument) – The document to render.

• fmt (OutputFormat) – The target format. MD returns a plain markdown body with no front matter; every other format prepends YAML front matter carrying the appropriate Quarto format block.

• theme (str | None) – HTML theme filename to reference in the front matter.

• reference_doc (str | None) – DOCX reference-doc filename to reference.

• typst_header (str | None) – Typst preamble filename to include for PDF output.

Returns:

str – The .qmd (or plain markdown) source.

Return type:

str

Formats

class jamb.publish.formats.OutputFormat

A document output format produced by jamb publish.

jamb.publish.formats.format_from_path(path)

Return the output format implied by a file extension.

Parameters:

path (str | Path) – The output path whose suffix selects the format.

Returns:

OutputFormat | None – The matching OutputFormat, or None when the extension is not recognized.

Return type:

OutputFormat | None

Rendering

jamb.publish.render.render_document(doc, fmt, output_path, *, template=None)

Render a document to output_path in the requested format.

Markdown and .qmd output are written directly. HTML, DOCX, and PDF are produced by invoking Quarto against a generated .qmd in an isolated temporary directory.

Parameters:

• doc (PublishDocument) – The document to render.

• fmt (OutputFormat) – The target output format.

• output_path (str | Path) – Destination file path.

• template (str | Path | None) – Optional styling override appropriate to the format — an SCSS file for HTML, a reference .docx for DOCX, or a Typst preamble for PDF. When omitted, the bundled defaults are applied so all three formats share the same look.

Raises:

• QuartoNotFoundError – When a rendered format is requested but Quarto is unavailable.

• QuartoRenderError – When Quarto fails to produce the output.

Return type:

None

jamb.publish.quarto.find_quarto()

Resolve the Quarto binary to an absolute path.

Resolution order: the JAMB_QUARTO environment variable, the binary bundled with the quarto-cli package, then any quarto on PATH.

Returns:

str – An absolute path to the Quarto binary.

Raises:

QuartoNotFoundError – When no binary can be found.

Return type:

str

jamb.publish.quarto.quarto_version()

Return the installed Quarto version string, or None if unavailable.

Return type:

str | None