Documentation
¶
Overview ¶
Package docgen renders the command reference, the llms pages and the docs/reference pages, from the live cobra tree.
Every part of a command's reference entry is already in cobra, and the hand-kept copy drifted: three anchor forms, two flag layouts, 28 leaf/flag pairs documented only in shared prose, and 62 commands with no section. Generating makes the gate "regenerate and diff", which a merely plausible doc cannot pass.
Only the text between the markers is generated (one row cut here):
<!-- BEGIN GENERATED: pgedge starfleet byoc cluster list --> ##### pgedge starfleet byoc cluster list **Usage:** `pgedge starfleet byoc cluster list [flags]` List clusters **Flags:** | Flag | Required | Default | Description | |------|----------|---------|-------------| | `--offset int` | No | | Offset into the results for pagination | <!-- END GENERATED -->
Everything outside the markers is hand-written and never touched: the generator owns what drifts silently, the author owns the prose.
The description is cobra's Short, not Long: Long carries worked examples that would duplicate the hand-written ones, and using Short means --help and the reference cannot disagree about a command.
Index ¶
- func Adopt(doc string, root *cobra.Command) (out string, adopted []string)
- func ApplyPage(doc, scope string, cmds []*cobra.Command) (string, error)
- func BeginMarker(path string) string
- func Block(cmd *cobra.Command) string
- func BlockCount(doc string) int
- func CheckPagingClaims(prose string, def, clamp int) error
- func CommandProse(doc, command string) (string, error)
- func Conform(doc string, want []*cobra.Command) []string
- func EndMarker() string
- func ExampleSection(long string) string
- func HasRouting(doc string) bool
- func MissingBlocks(want []*cobra.Command, missing []string) string
- func Page(cmds []*cobra.Command) string
- func PageBeginMarker(scope string) string
- func PageEndMarker() string
- func Routing(scope string, children []RoutingEntry) string
- func RoutingBeginMarker(scope string) string
- func RoutingEndMarker() string
- func VisibleCommands(root *cobra.Command) []*cobra.Command
- type Result
- type RoutingEntry
- type RoutingResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Adopt ¶
Adopt replaces the hand-written section for each command in root that has a `**Usage:**` line but no generated block, and returns the rewritten document plus the paths it adopted.
Commands with neither a block nor a usage line are left for Apply to report as Missing: this function will not guess where a section belongs, because a generator that invents placement scatters the reference and there is no way to review that automatically.
func ApplyPage ¶
ApplyPage replaces the text between a page's markers with the rendered region for its commands. Absent, duplicated or misordered markers are an error, not a skip: the pages are a fixed table, so a broken one is drift.
func BeginMarker ¶
BeginMarker returns the opening marker for a command path.
func BlockCount ¶
BlockCount reports how many generated blocks doc contains, so a caller can tell a clean pass from a run whose markers stopped matching: both report zero violations.
func CheckPagingClaims ¶
CheckPagingClaims is the INVERSE assertion: it reports an error unless the page-size and clamp claims a command's prose makes are EXACTLY the ones def and clamp can produce. A zero or negative argument means the code records no such number, so the prose must make no claim of that shape at all.
A Contains over the expected phrase catches only a missing claim, not a stale number left beside the fresh one, a drift that has shipped twice. "above 200 is clamped" beside the true "above 100 is clamped" passed a Contains check, as did a second page size. So this finds every sentence of either shape and requires exactly {def} and {clamp}.
The caller passes one command's span (CommandProse), so a neighbouring verb's page size is out of scope.
func CommandProse ¶
CommandProse returns the HAND-WRITTEN prose for one command in a reference document: the span between the end of that command's own generated block and the start of the next generated block or heading. Whitespace is collapsed, so an assertion over the result cannot be defeated by a hard wrap falling between two words of the phrase it looks for.
The byoc and managed paging gates share it. Each rule stops an assertion passing vacuously:
- the marker must be a whole line, or a marker quoted in prose anchors the span on another command's text.
- the marker must be unique: a duplicated cobra registration makes `make docs` emit a duplicate block, and the first would win.
- whitespace is collapsed: a line broken between "100 rows by" and "default" defeated a phrase match.
- empty prose is an error, or a command whose hand-written half was deleted satisfies every "does not contain" assertion.
It returns an error rather than taking a *testing.T to keep the testing import out of this package.
func Conform ¶
Conform reports every way doc fails to be a conforming reference for want, as human-readable messages. Empty means conforming.
It is the only definition of conforming. A second check, parsing `**Usage:**`-anchored sections for each command's flags, would only compare generated text with the tree that generated it; a drifted block is caught here, byte for byte.
func ExampleSection ¶
ExampleSection returns the commands under a Long string's trailing "Example:" heading, dedented, or "" when there is none.
It reads Long, not cobra's Example field, which this tree never populates: every example sits in Long under this heading, which internal/clitest's example gate depends on too. A silent "" is caught by TestEveryLeafCarriesAnExtractableExample.
The section runs to the end of Long: measured 2026-08-29, no Long carries unindented text after its Example heading.
func HasRouting ¶
HasRouting reports whether doc carries a routing table.
func MissingBlocks ¶
MissingBlocks renders the blocks for every path in missing, so both the generator and a failing gate can show the author exactly what to paste.
func Page ¶
Page renders a reference page's generated region: every command's section in order, no per-command markers, headings re-levelled so the shallowest command sits at h2 under the page's hand-written h1.
func PageBeginMarker ¶
PageBeginMarker returns the opening marker for a page's generated region. The scope is a command-path prefix under root ("starfleet byoc", "controlplane"), or "" for the index page; the marker names the full path.
func PageEndMarker ¶
func PageEndMarker() string
PageEndMarker returns the closing marker for a page's generated region.
func Routing ¶
func Routing(scope string, children []RoutingEntry) string
Routing renders the table for scope's children. The `Read` column is the exact command to run, because the table exists to be followed, not admired.
func RoutingBeginMarker ¶
RoutingBeginMarker returns the opening marker for a scope's table.
Types ¶
type Result ¶
type Result struct {
Doc string
Changed int // blocks whose rendered content differed
Missing []string // commands the document should cover but does not
Foreign []string // blocks for commands this document should not cover
}
Result reports what Apply did and what it left for a human. Missing and Foreign are never resolved automatically: placing a new block would scatter the reference, and deleting one would lose the prose beside it.
type RoutingEntry ¶
RoutingEntry is one row: the page's scope and the Short of the command it documents, so the table says what each page is for in the command tree's own words.
type RoutingResult ¶
type RoutingResult struct {
Doc string
Changed bool
// Missing is set when the page has children but no table to list
// them in. The generator will not guess where the table belongs;
// it reports the block to paste, as it does for a command block.
Missing bool
// Stray is set when the page has a table but no children, which
// is a table that lists nothing and should be removed.
Stray bool
// Foreign names the scope a table declares when it is not this
// page's own — a table pasted from another index.
Foreign string
// Duplicate is set when the page carries more than one table. Two
// identical tables would otherwise rewrite to themselves and pass.
Duplicate bool
}
RoutingResult reports what ApplyRouting found.
func ApplyRouting ¶
func ApplyRouting(doc, scope string, children []RoutingEntry, ) RoutingResult
ApplyRouting rewrites the routing table in doc for scope's children, or reports what stops it.
Source Files