Module generated_doc 

The GeneratedDoc contract, and the pragma splice that enforces it.

A generated page is a hand-written page with a hole in it. The hole is delimited by two HTML comments —

<!-- Begin auto-generated <label> -->
<!-- End auto-generated <label> -->

— and this module is the only code that touches what lies between them. Everything outside is the author’s: introduction, caveats, cross-links. The four requirements of docs/design/11-documentation-plan.md §17.6 are all enforced here rather than left to each generator:

• idempotent — the splice is a pure function of (framing, rendered content), so writing twice writes the same bytes;
• deterministic — nothing in this module reads a clock, an environment variable or a hash map, and the only absolute path it forms is the one used to open a file, never one it emits;
• fail-closed — a missing page, a missing pragma, a doubled pragma and a generator that returns Err all stop the run in every mode;
• framing-preserving — the expected bytes are built by copying the framing from disk, so --mode check cannot fail on prose and --mode write cannot destroy it.

Enums

Framing

How a generator’s output relates to the file that holds it.

Mode

What generate-all does to the pages.

Outcome

What one generator did.

Traits

GeneratedDoc

One generated documentation region.

Functions

begin_pragma 🔒

The opening pragma for label.

drift 🔒

Builds the Error::Drift that --mode check fails with, naming the first line on which the page and the generator disagree.

end_pragma 🔒

The closing pragma for label.

guard_no_pragma 🔒

Rejects rendered content that carries a pragma of its own.

normalise_final_newline 🔒

Ends a page with exactly one newline.

pragma_error 🔒

Builds an Error::Pragma for this page.

repo_root

The repository root.

run_one

Runs one generator under mode.

site_links_page_relative 🔒

Renders one generator’s output, with this site’s own absolute URLs made page-relative.

sole_line 🔒

Locates marker, requiring it to appear exactly once and alone on its line.

splice 🔒

Builds the bytes the page should hold: its own framing, with content between the pragmas.

whole_file 🔒

Builds the bytes a Framing::WholeFile output should hold.