Documentation
¶
Overview ¶
Package docgen contains helpers for generated project documentation.
The package renders source-readable Markdown tables and normalizes existing GitHub-flavored Markdown pipe tables while preserving fenced code blocks, escaped pipe characters, inline code spans, Unicode cell widths, and original line endings. Command packages use these helpers when refreshing README and docs content so generated files stay stable in diffs and easy to review as plain text.
It also owns the two ways a command puts bytes on disk, kept apart because they answer different questions. WriteOrCheck is the whole-file freshness convention for a committed artifact: one file mode, one directory mode, one line-ending-agnostic comparison, one trailing newline and one "is stale; run …" sentence. WriteReport is the "-" means stdout convention for an auditor's -output flag, where nothing is committed and nothing is compared.
Neither absorbs ReplaceSection and ComputeReplacedSection, which rewrite a marked region of a hand-written file rather than owning the whole of it; what is generated there is a section, and the rest of the file is somebody's prose.
Index ¶
- func ComputeReplacedSection(text, startMark, endMark, content string) (string, error)
- func FormatMarkdownTables(content string) (string, bool)
- func NormalizeNewlines(b []byte) []byte
- func RenderMarkdownTable(headers []string, alignments []Alignment, rows [][]string) string
- func ReplaceSection(path, startMark, endMark, content string) error
- func WriteOrCheck(path string, content []byte, check bool, regenerate string) error
- func WriteReport(path string, content []byte) error
- type Alignment
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComputeReplacedSection ¶
ComputeReplacedSection returns text with the content between startMark and endMark replaced by content. It returns an error when either marker is absent, so callers fail fast instead of writing a malformed file.
func FormatMarkdownTables ¶
FormatMarkdownTables normalizes GitHub-flavored Markdown pipe tables in content. Tables inside fenced code blocks are left unchanged.
func NormalizeNewlines ¶
NormalizeNewlines strips carriage returns so a comparison of generated text is line-ending agnostic across platforms. It is what WriteOrCheck compares through, and it is exported because the commands whose artifacts it writes hold the same bytes to the same rule in their own tests: three private spellings of this one line is exactly what this package exists to stop.
func RenderMarkdownTable ¶
RenderMarkdownTable returns a Markdown table padded to the widest cell in each column so the generated source remains readable as plain text.
func ReplaceSection ¶
ReplaceSection rewrites the file at path, replacing the content between startMark and endMark (both preserved) with content. It is used by the generator commands that maintain managed README/doc sections.
func WriteOrCheck ¶
WriteOrCheck writes content to path, or -- when check is set -- reports whether the file already there holds exactly that content. It is the one place the whole-file freshness convention is decided for the generators that own a committed artifact: the comparison is line-ending agnostic, so a Windows checkout does not report drift a Linux one does not see; content is given the trailing newline that keeps a generated file from being the one text file in the repository without one; a write creates the parent directory, while a check never does, so a gate reports a missing tree rather than making one; and a stale artifact is reported with one sentence naming the file and the command that refreshes it, which regenerate supplies.
The file is written through an os.Root opened on its directory, so the write can only ever land on the named file: that containment came from cmd/gen_llms and cmd/gen_lhm_manifest, and giving every caller the strictest of the merged behaviors is cheaper than explaining which two commands keep it.
This is deliberately not the same function as WriteReport. A generated artifact is a file the repository commits and CI compares; a report is a destination an operator names on a flag, where "-" means stdout and no freshness question is being asked. One function with a mode flag would put two contracts behind one signature.
func WriteReport ¶
WriteReport writes an audit's report to path, where the sentinel "-" means stdout. It is the one place that convention is decided for the auditors whose -output flag names a file the repository does not commit.
Unlike WriteOrCheck the path is the operator's own, so nothing here is contained to a directory and nothing is compared: the report is whatever this run found, and the only question is where it lands.
Source Files