Get started

Check the docs in CI

In this step you run docgen check on each pull request, so that a change to the code cannot leave a page out of date. The GitHub Action is the shortest way.

Add the GitHub Action§

Add a workflow, such as .github/workflows/docs.yaml. The action runs docgen check -diff, so a failed run shows each change in its log:

name: Docs

on:
  pull_request:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - uses: USA-RedDragon/docgen@v0.1.0

docgen runs the go command to load the packages of your module, so set up Go before the action. The inputs:

An empty input adds no flag, so the settings apply. The exit code of docgen is the exit code of the step. The action is in action.yml.

How the action gets docgen:

• A release tag, such as v0.1.0 in uses: or in version, downloads the prebuilt docgen of that release with gh. The action checks its sha256 against the checksums.txt of the release, and stops on a mismatch. This takes about a second.
• A branch or a commit SHA in uses: builds docgen from the code at that ref. The build is cached, so the next run with the same code does not build again. Another version, such as latest, installs with go install. Only these two cases use Go to get docgen.
• When a release has no archive for the runner, or gh cannot download it, the action gets docgen from source with Go: a build of the tag in uses:, or go install of the version.

Comment on the pull request§

With comment: true, a check run on a pull_request event also puts the result in one comment on the pull request. The job needs pull-requests: write:

permissions:
  contents: read
  pull-requests: write

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - uses: USA-RedDragon/docgen@v0.1.0
        with:
          comment: true

• The comment holds the stale, unused and broken lines, and the diff in a closed <details> block.
• A hidden HTML comment, <!-- docgen-check --> with the default marker, starts the comment. The next run edits that comment and adds no other.
• When the docs are current, the comment changes to one line: the docs are current. It stays, so the pull request keeps a record of the earlier result. With no earlier comment, a clean run adds none.
• A GitHub comment holds at most 65536 characters. A longer result is cut to fit, with a note, and the log of the job has all of it.
• The token of a pull request from a fork cannot write. Then the log shows a warning, and the step does not fail for that reason alone.
• The exit code of docgen stays the exit code of the step. The comment uses gh api, which is on GitHub-hosted runners.

Use go run instead§

Here is the step of the docs workflow:

- name: Check the generated parts of the docs
  run: go run . check

In your repository, run docgen by its version:

- name: Check the generated parts of the docs
  run: go run github.com/USA-RedDragon/docgen@v0.1.0 check

No setup step is necessary. The go command downloads the modules at the versions that go.mod and go.sum pin.

Check before each commit§

To find stale docs before you push, run the same check in a pre-commit hook. See Use pre-commit.

What fails the check§

• A marker body that differs from what update writes.
• A generated file, such as a state diagram, that differs or is missing.
• A marker with the name of something that does not exist, such as a removed constant.
• A failed test or Example, for docgen:states and docgen:output.
• An excerpt with lines= whose file changed.
• A region, a diagram or a variable that no marker uses, and a region mark with no pair.
• A link, image or anchor that reaches nothing.

The output gives the page and the line of each result. For the exit codes, see Command line.

Next§

Go to Document a config struct and the other guides for each marker kind.

Source: docs/start/03-check-in-ci.md