Documentation in CI: make code changes easier to review

Define what a documentation check should prove

A successful documentation job should tell a reviewer which artifact was produced and whether it matches the intended source revision. It should not imply that every explanation is correct just because a generator exited successfully. Begin with a small check: regenerate deterministic pages in a clean working copy and review their diff.

Keep the initial job separate from deployment. That lets a team inspect changed Markdown before a documentation site is published.

Use scaffolding for a predictable starting point

Build RepoDocs from a pinned revision. Run scaffold against a disposable checkout of the project. The command writes documentation and MkDocs configuration, so start with a clean tree and capture the generated diff as a review artifact. Use a repository path explicitly rather than relying on the job’s working directory.

cargo build --release -p repodocs-cli
cargo run --release -p repodocs-cli -- scaffold /path/to/checkout
# In the target checkout, inspect the output before publishing:
git diff -- docs mkdocs.yml

Add impact analysis deliberately

The CLI also exposes analyze with an optional local diff and ci with an event, repository path, and revision options. Confirm those options with the CLI help from your pinned build. LLM-assisted documentation generation and external publishing need their own configuration and credentials.

Start by retaining the impact report for human review. Do not make a generated severity label the sole reason to reject a change until you have tested it against representative changes in your repository.

1. Pin the generator revision and record its version or commit.
2. Run a known small source change through a disposable checkout.
3. Compare the report with the files a reviewer expects to be affected.
4. Test a failed generator run and ensure the job reports failure.
5. Keep provider and publishing credentials out of logs and generated pages.

Decide when a difference should block a merge

One team may require checked-in generated Markdown to match the code. Another may attach the new pages as an artifact and ask a reviewer to accept them. Record that policy before adding a blocking job. Otherwise harmless formatting changes can create noise while missing architectural explanations still pass.

The current RepoDocs offering is CLI based. Subscribe for updates on the landing page to follow improvements to CI workflows; managed CI or hosted onboarding is not implied.