docgen

Reference

Command line

The commands, flags and exit codes of docgen. For the settings, see Configuration.

Usage§

Usage: docgen <command> [flags] [directory]

Commands:
  update  fill in the markers
  check   list stale markers, unused regions and broken links, and exit 1 if there are any

Arguments:
  directory  the directory to scan (default the repository, or docs: in .docgen.yaml)

Flags:
  -config string
        config file (default ".docgen.yaml")
  -diff
        with check, print a unified diff of each stale page and generated file
  -jobs int
        -p of each go command; 0 leaves it to go
  -module string
        directory of the Go module, relative to the repository root (default ".")
  -tags string
        comma-separated build tags of each go command and package load

A flag goes before the directory. The flags -module, -tags and -jobs override the settings of the same name, and the directory overrides docs. For the repository root, see The file. For the scan, see Choose what to scan.

See a diff§

check -diff prints a unified diff of each stale page and generated file to standard output, so docgen check -diff | patch -p0 at the root applies it. All other output goes to standard error.

What check reports§

check also reads the repository, and update does not. Each result is a line on standard error, sorted, and check exits 1.

  • unused: path:line: docgen:region name is a region that no region= of a scanned page excerpts. The scan starts at the repository root, skips the directories of a page scan, the paths that git ignores other than scanned pages, and the pages under a docgen:docgen root, and skips binary files and files over 1 MiB. A path that cannot be read is an error, and the other results still print.
  • unused: path: docgen:states diagram is an SVG file in a states directory next to a scanned page that no docgen:states marker writes.
  • unused: .docgen.yaml: var name is a variable of the vars setting that no marker of a scanned page reads. The path is the config file of the run.
  • broken: page:line: target is a link, image or reference definition of a scanned page that reaches nothing: a missing file, a path that leaves the repository, a missing anchor, or a label with no definition. Anchors follow the rules of GitHub. A path that starts with / is relative to the repository root. Links with a scheme are not fetched. Code and HTML blocks are text. Line numbers refer to the text that update writes.

A region mark with no pair, and a name twice in one file, are errors with path and line.

Exit codes§

Code Meaning
0 The run finished. With check, nothing is stale, unused or broken.
1 With check, a marker is stale, a region, diagram or variable is unused, or a link is broken. With either command, a marker has an error, a test or Example that it uses failed, a setting has a value that is not valid, or a setting holds a directory or file that does not exist. An interrupt or a SIGTERM also stops the run with exit 1 and writes nothing.
2 The command line is not valid: no command, an unknown command, an unknown flag, a flag value that does not parse, or an extra argument.
  • update writes nothing when a marker fails.
  • check lists stale markers and marker errors together, each with its page and line.
  • An error that stops a package from loading names the package.

Source: docs/reference/command.md