docexamples

Overview ¶

Command docexamples keeps the Go blocks of documentation pages in step with compiled Example functions, so a page cannot show code that no longer builds.

go run ./scripts/docexamples generate page.md ...
go run ./scripts/docexamples check page.md ...

A page marks a generated block with the package directory and the name of an Example function in that package's test files:

<!-- doc-example: pkg/kubernetes/metallb ExampleCreateIPAddressPool -->
```go
pool := metallb.CreateIPAddressPool("my-pool", "metallb-system")
```
<!-- doc-example:end -->

and a block that cannot be one, with the reason:

<!-- doc-example:excerpt shows a type declaration, not a call -->
```go

generate replaces everything between a doc-example marker and its end marker with the Example's body: the statements between its braces, less one level of indentation, each remaining leading tab written as four spaces, and without its output comment or anything after it. As in go test, the output comment is the body's last comment, when it starts with "Output:" or "Unordered output:" in any case. A new block is added by writing the two markers and running generate.

check changes nothing and fails when generate would change a page, or when a page has a ```go block (or ```golang, in any case) that is neither generated nor marked as an excerpt. A marker line it does not recognise, an excerpt marker with no reason or not directly above a ```go fence, a doc-example marker with no end marker, and an Example that does not exist are errors in both modes.

Markers inside a fenced block are text, not markers, and a ```go block inside another fence is not a block of the page. A marker may be indented, as inside a list item; the generated block takes its indentation.