docgen

Guides

Show output

Put the output of an Example, a program or a command in a page.

An Example§

go test checks the // Output: comment, so a wrong comment fails the run.

v2/machine/example_test.go

func ExampleLamp() {
    l, _ := machine.NewLamp(machine.Config{})
    _ = l.Start(0)
    fmt.Println(l.State() == machine.LampOn)
}

docs/machines/guide-output.md

Before
# Example

<!-- docgen:output test=machine.ExampleLamp -->
<!-- /docgen:output -->
After
# Example

<!-- docgen:output test=machine.ExampleLamp -->
```text
true
```
<!-- /docgen:output -->
Preview

Example

true

A program or a command§

cmd= runs the Go program in any directory of the repository. exec= runs a shell command in the repository root.

v2/examples/hello/main.go

func main() {
    fmt.Println("hello from the fixture")
}

v2/go.mod

module github.com/USA-RedDragon/docgen/v2

go 1.24.0

docs/machines/guide-output-run.md

Before
<!-- docgen:output cmd=v2/examples/hello -->
<!-- /docgen:output -->

<!-- docgen:output exec="head -n 1 v2/go.mod" -->
<!-- /docgen:output -->
After
<!-- docgen:output cmd=v2/examples/hello -->
```text
hello from the fixture
```
<!-- /docgen:output -->

<!-- docgen:output exec="head -n 1 v2/go.mod" -->
```text
module github.com/USA-RedDragon/docgen/v2
```
<!-- /docgen:output -->
Preview
hello from the fixture
module github.com/USA-RedDragon/docgen/v2

Both run on each update and check, also in CI. The output must be the same on each run, and a nonzero exit status is an error.

For all options, see docgen:output.

Source: docs/guides/output.md