Documentation
¶
Overview ¶
Package refdoc renders the parts of the reference pages that state what the code exposes, and checks that the pages still hold what the renderers produce.
A generated block is the text between two marker lines in a Markdown page:
<!-- refdoc:begin settings --> (rendered text) <!-- refdoc:end settings -->
The name matches ^[a-z0-9-]+$, is unique within the page, and the end marker repeats it. Everything outside the markers is hand-written and stays byte for byte as it is. The text between them belongs to a renderer and is replaced whole: it is the lines between the markers joined by newlines and closed by one, and it is empty for a block whose markers are adjacent.
Verify is the only function here that touches a page. The renderers return strings, and a test hands them to Verify together with the page they belong in, so a page that drifts from the code fails `go test ./...` rather than being noticed by a reader. Verify checks the blocks it is handed and no others.
With TALLY_UPDATE_DOCS=1 in the environment, Verify writes the rendered text into the page instead of reporting the mismatch, which is how the pages are regenerated after a change to the code they describe. A rewrite holds the exclusive lock of the page while it reads and writes it, so the test binaries of the packages that write blocks of one page may regenerate it at once.
Index ¶
- func AlertRouting(cfg []byte) (string, error)
- func AlertRules(rules []byte) (string, error)
- func Commands(root *cobra.Command) (string, error)
- func Consts(src []byte, names ...string) (string, error)
- func Dashboards(files map[string][]byte) (string, error)
- func Fenced(lang string, body []byte) string
- func Flags(fs *flag.FlagSet) (string, error)
- func JSONSchema(schema []byte) (string, error)
- func MakeTargets(makefile []byte) (string, error)
- func MappingTable(src []byte) (string, error)
- func Metrics(reg *prometheus.Registry) (string, error)
- func OpenAPIOperations(doc *openapi3.T) (string, error)
- func OpenAPISchemas(doc *openapi3.T) (string, error)
- func OpenAPISecurity(doc *openapi3.T) (string, error)
- func ScrapeJobs(cfg []byte) (string, error)
- func Settings(src []byte, structName string, envNames []string) (string, error)
- func Struct(src []byte, tagKey string, typeNames ...string) (string, error)
- func Verify(t testing.TB, page string, blocks map[string]string)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AlertRouting ¶
AlertRouting renders where a fired alert goes: the grouping the root route holds every alert to, what each child route changes about it, and whether a receiver carries a delivery integration at all.
func AlertRules ¶
AlertRules renders the rules an evaluator loads: a paragraph per group and a section per rule, in the order the file writes them.
The summary and the expression are fenced rather than written into the prose. Both carry Go templates such as {{ $labels.cloud }}, which the site would otherwise read as an interpolation of its own and evaluate against nothing.
func Commands ¶
Commands renders a cobra command tree: one section per command, depth first from the root, children in the order the tree holds them.
A command cobra generates rather than the tool declaring it, and one the tree hides or deprecates, is left out with everything under it: a page documenting them would describe cobra rather than the tool.
func Consts ¶
Consts renders named constants as a table of the value each one holds and what the code says it means, in the order the caller names them.
func Dashboards ¶
Dashboards renders the provisioned dashboards: one section per file in name order, with the variables it takes and the query behind every panel.
A text carrying a Go template, a backtick or a line break is refused rather than rendered. A table cell is not fenced, so the site would read the braces as an interpolation of its own, a backtick would close the code span the text stands in and let the rest of it out, and a row of a table ends at the first line break; a dashboard that needs any of them belongs in a fenced block a page writes by hand.
func Fenced ¶
Fenced renders body as a fenced code block tagged lang. The fence is one backtick longer than the longest run of backticks in the body, so a body that carries a fence of its own stays inside the block. The body ends in exactly one newline, and an empty body renders an empty block.
func Flags ¶
Flags renders the flags of a standard library flag set, in the order the set reports them. The type comes from the name flag.UnquoteUsage derives, which is also what strips the backquotes from the usage.
func JSONSchema ¶
JSONSchema renders a JSON Schema draft 2020-12 document: a paragraph naming the document, then one section per schema object, the root first and the definitions after it in the order the file writes them.
A section carrying properties is a table of them with the constraints each one is held to, followed by the sentence that says what else the object admits. A section without properties is one sentence stating what the value is.
func MakeTargets ¶
MakeTargets renders the public targets of a Makefile: one row per help comment of the form `## target: description`, in the order the file writes them. A target is public when it carries such a comment; a recipe without one is an implementation detail of another target and is not listed. A help comment naming something the file defines no rule for is an error: a comment that groups the targets below it reads as one, and publishing it would document a target `make` does not have.
func MappingTable ¶
MappingTable renders the collector's mapping from oslo notification types to Tally events: one row per entry of the mappings literal, in the order the source declares them. The state, the size and the skip columns name the function an entry derives the value with rather than describing it, because that name is what a reader looks up in the same file.
func Metrics ¶
func Metrics(reg *prometheus.Registry) (string, error)
Metrics renders the series a registry carries: one row per tally_ series in name order, with the labels it is broken down by and what the code says it counts.
The type comes from the exposition format where the registry holds a value, and from the name where it does not, because a vector without a child is gathered as nothing. A series whose type and name disagree is refused rather than rendered: the name is what a query is written against, so the two saying different things is a fault in the instrument.
func OpenAPIOperations ¶
OpenAPIOperations renders one section per operation: the paths in the order the router matches them, and the methods of a path in the fixed order a reader walks them.
A section says what the operation does, which credential it takes, what it reads off the request, and what every status it answers with carries. The bodies link to the schema page rather than repeating the members here, so one schema is described in one place.
func OpenAPISchemas ¶
OpenAPISchemas renders the component schemas: one section per schema in name order, with a table of the members it declares. A schema that declares no member is one sentence stating what the value is.
func OpenAPISecurity ¶
OpenAPISecurity renders the credentials the contract declares: one row per security scheme, in name order, with what the document says the credential is and how it reaches the server.
func ScrapeJobs ¶
ScrapeJobs renders the jobs a store scrapes: one row per job in the order the file writes them, with what it scrapes and how often.
A job that discovers its targets names none, so the cell states what it discovers and which of the discovered targets it keeps. That is the whole difference between a job that goes silent as one target and one that goes silent as no target at all.
func Settings ¶
Settings renders the environment variables a configuration struct reads: one row per field carrying an env tag, in the order the struct declares them. envNames is every variable the package reads, which is where the *_FILE companion of a secret is looked up.
A tagged field without a doc comment is refused rather than rendered with an empty cell: the comment is what the page tells an operator about the setting, and a row without it says only that the variable exists.
func Struct ¶
Struct renders the members of one or more document types: a heading per type, what the code says the type is, and a table of the members its tags name. tagKey is the tag the wire format is spelled in, json or yaml.
A member whose type is one of the types named in the same call links to that type's heading, so a reader follows a document into the one it carries. A field without a name, one the tag leaves out, and one tagged - are not part of the wire format and are left out of the table.
A comment that names a file or an argument with a placeholder in angle brackets has that token rendered in a code span. The site reads a bare <key> as markup, so a comment carrying one would fail the build of the page it reaches rather than show the name it spells.
func Verify ¶
Verify compares every named block of page with the text a renderer produced for it, and fails t for each block that differs. The map is keyed by block name; a name the page carries no markers for is a failure of its own, because a renderer whose block was dropped from the page would otherwise be verified against nothing.
With TALLY_UPDATE_DOCS=1 a differing block is rewritten instead: the page then holds the rendered text, and the markers and every byte outside them are unchanged.
Types ¶
This section is empty.
Source Files