docgen
docgen fills the facts in your Markdown docs from your Go code. You write the prose and put a marker where a fact from the code goes. docgen update writes the fact into the marker, and docgen check fails in CI when a page no longer matches the code.
Installation§
Install the command. The minimum Go version is 1.27.0.
go install github.com/USA-RedDragon/docgen@latest- GitHub Action:
uses: USA-RedDragon/docgen@v0.1.0. See Check the docs in CI. - pre-commit hook:
id: docgen-checkof the repositoryhttps://github.com/USA-RedDragon/docgen. See Use pre-commit.
Getting started§
Put a marker in any Markdown page:
The client waits <!-- docgen:const pkg=client name=DefaultTimeout --><!-- /docgen:const --> for a reply.Fill it from the root of the repository:
docgen updatedocgen writes the value between the two comments:
The client waits <!-- docgen:const pkg=client name=DefaultTimeout -->`30s`<!-- /docgen:const --> for a reply.Run docgen check in CI. It changes nothing, and exits 1 when a page is out of date. For each step, see Your first page.
Features§
For the full list, see Markers.
- Constants and
go.modlines, inline in a sentence. - Tables of config structs. The default of each field comes from the code that applies it, not from the doc text.
- Tables of the errors that the doc comments of a type name.
- State tables and SVG diagrams of state machines, recorded from what your tests do.
- Doc comments as Markdown.
- Code excerpts by symbol from Go, YAML and C files, and by marked region or line range from any file.
- The output of Examples and example programs, and the
-husage of commands. - A version or another value from
.docgen.yaml, in a sentence or a code block.
Documentation§
Read the docs at https://docgen.mcswain.dev/. Each release has its own version of the docs.
Versioning§
- A patch release never breaks your pages or your CI.
- A minor release can add markers and flags, and can make a breaking change. See Versioning.
- The minimum Go version only goes up in a minor or major release.
Source: README.md