Guides

Use pre-commit

Run docgen check before each commit with pre-commit, so that stale docs never reach a pull request.

Add the hooks§

Add docgen to .pre-commit-config.yaml at the repository root:

repos:
  - repo: https://github.com/USA-RedDragon/docgen
    rev: v0.1.0
    hooks:
      - id: docgen-check
      - id: docgen-update

Then install the git hook:

pre-commit install

pre-commit builds docgen with Go at the rev that you give, and installs Go when it is not on PATH.

Hook	Runs	Does
`docgen-check`	on each commit	`docgen check`. The commit stops when a page is stale.
`docgen-update`	only when you ask	`docgen update`. It fills the markers.

docgen-check runs on each commit, also when no Markdown or Go file changed, because a page can quote any file.

To also check before each push, install that hook type too: pre-commit install --hook-type pre-push.

When docgen-check stops a commit, fill the markers, then add the changes and commit again:

pre-commit run --hook-stage manual docgen-update
git add -A
git commit

Run the check on the whole repository, for example after you add the hooks:

pre-commit run docgen-check --all-files

Give flags with args:, such as a module in a subdirectory:

      - id: docgen-check
        args: [-module, v2]

The settings in .docgen.yaml also apply, so most repositories need no args:.