docgen

Reference

Configuration

The settings of docgen, with the key in .docgen.yaml, the environment variable and the flag of each.

Settings§

Key Type Default Environment Flag Description
docs string . DOCGEN_DOCS — directory to scan for Markdown pages, relative to the repository root
module string . DOCGEN_MODULE --module directory of the Go module, relative to the repository root
jobs integer 0 DOCGEN_JOBS --jobs -p of each go command; 0 leaves it to go
tags string DOCGEN_TAGS --tags comma-separated build tags of each go command and package load
depth integer 1 DOCGEN_DEPTH — levels of nested docgen:docgen markers; 0 allows none
print string go DOCGEN_PRINT — how a marker with no print= prints a value: go, or raw, which runs no code
vars map of string — — values of the docgen:var and docgen:text markers, by name
  • vars holds the values of the docgen:var and docgen:text markers. It is a setting of the file only. A key has letters, digits, _ and -.
  • jobs is the -p of each go command, an integer up to 1024. 0 adds no -p. At most 8 go commands run at once for any value. Use it to limit a small CI runner.
  • tags holds letters, digits, _ and ., separated by commas. A -tags in GOFLAGS also applies.
  • depth is at most 8.
  • An unknown key is an error.

Example§

A repository with its pages in documentation and its module in v2:

docs: documentation
module: v2
tags: integration,linux
jobs: 4
vars:
  version: v1.2.3

Order of precedence§

A later item overrides an earlier one:

  1. Defaults.
  2. The file.
  3. Environment variables.
  4. Flags and the directory argument.
# .docgen.yaml has jobs: 4.
DOCGEN_JOBS=2 docgen check          # jobs is 2
DOCGEN_JOBS=2 docgen check -jobs 1  # jobs is 1

The file§

  • The file is .docgen.yaml at the repository root. It is optional.
  • -config names another file, with the extension .yaml or .yml. That file must exist.
  • The repository root is the nearest directory at or above the working directory with a .docgen.yaml file or a .git entry, or else the working directory.

Choose what to scan§

docgen scans each Markdown file of the repository.

Scan How
The whole repository The default.
One directory on each run docs: documentation in .docgen.yaml
One directory on one run docgen update documentation

The directory argument replaces docs and is relative to the working directory. A marker outside the directory stays as it is.

A scan skips:

  • testdata, vendor and node_modules.
  • Directories whose names start with . or _.
  • Paths that git ignores. A directory named by the argument or docs is scanned also when git ignores it, and a .gitignore below it applies.
  • Pages under the root of a docgen:docgen marker.
  • Anything that is not a regular file, such as a symlink.

Go environment§

docgen runs go with your environment, so GOPROXY, GOWORK and GOFLAGS work as they do for any go command. The go command downloads missing modules at the versions that go.mod and go.sum pin. Set GOPROXY=off to forbid the network. jobs adds -p to GOFLAGS and tags adds -tags, joined with the value of go env -w GOFLAGS.

GOTMPDIR is a new directory for each run, below docgen in the user cache directory, so that builds are not on a tmpfs. docgen removes it at the end of the run, also after an interrupt, so a go command that the interrupt ends leaves no build directory.

For the commands and flags, see Command line.

Source: docs/reference/configuration.md