Agent Wranglers

DOC-8Recommended

Build the docs in CI and fail on every warning

Build the docs site on every pull request with warnings treated as errors. A broken internal link, a missing page in the menu or a bad cross-reference fails the build.

By Agent Wranglers. Updated .

How to do it

Docs that live in the repository change in the same pull request as the code, as Change the docs in the same pull request says. The build is what keeps them whole. Turn on the strict mode of the docs tool, such as mkdocs build --strict, sphinx-build -W or onBrokenLinks: 'throw' in Docusaurus. Then run a link checker and the code samples, as Test the docs in the build says. Publish the docs from the same pipeline, never by hand from a laptop.

Examples

YAML example

docs:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - run: pip install -r docs/requirements.txt
    - run: mkdocs build --strict
    - run: lychee --offline site/

YAML example 2

# Sphinx equivalent: -W turns warnings into errors, --keep-going lists them all
docs:
  script:
    - pip install -r docs/requirements.txt
    - sphinx-build -W --keep-going -b html docs/ public/

How to check

On a branch, add a link to a page that does not exist. The docs job in CI fails and names the file and the link.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/strict-docs-build">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.