Docs Maintenance #

How documentation stays consistent with the codebase across tools, branches, and contributors.

Enforcement Layers #

Pulp uses three layers to keep docs aligned with code:

1. CI Check (local truth + manual cloud companion) #

The authoritative docs consistency check is tools/check-docs.sh, which you can run locally or through the docs-check.yml workflow. The current GitHub Actions workflow is workflow_dispatch-only; it does not run automatically on every push or PR in the current repo state.

tools/check-docs.sh validates:

• Every .md file in docs/ is indexed in docs/status/docs-index.yaml
• Every path referenced in YAML manifests resolves to a real file
• All status: values use the allowed vocabulary
• Module dependencies in modules.yaml match CMake target_link_libraries
• Format adapters claimed in support-matrix.yaml have real source files
• Subsystem directories listed in modules.yaml exist

If any check fails, the local docs check or manually dispatched workflow fails.

2. Claude Code Hook (agent nudge) #

A PostToolUse hook in .claude/settings.json fires after file edits. When an agent modifies files in core/, examples/, or tools/cli/, it prints a reminder to update docs and manifests. This is a soft nudge, not a blocker.

3. AGENTS.md (multi-tool contract) #

The repo-root AGENTS.md file is read by both Claude Code and Codex CLI. It contains the docs maintenance rule: when you modify source files that affect public behavior, update the relevant YAML manifests and Markdown docs.

Local Validation #

Run the docs consistency check locally at any time:

# Via the CLI
./build/tools/cli/pulp docs check

# Directly
tools/check-docs.sh

Both do the same thing: run all manifest/link/vocabulary/dependency checks and report errors and warnings.

What Triggers a Docs Update #

Branch Model #

Docs version with the branch they live on:

• main docs describe what is stable and released
• develop docs describe what is in development
• When develop merges to main, docs merge too

Not every workflow is always-on in the current repo state. Some workflows remain manual workflow_dispatch entry points while the repo stays local-first for CI.

That means branch truth should be documented explicitly instead of assuming an always-on cloud gate for every workflow.

README Accuracy #

The CI check also validates that README.md's claimed test count matches the actual ctest count in the build directory. This catches drift like "53 tests" persisting while the repo has 270.

Docs Site #

The docs site at generouscorp.com/pulp/ is generated from the same docs/ files:

• Build locally: pulp docs build-site or python3 tools/build-docs.py
• Deploy: the docs-deploy.yml GitHub Actions workflow builds and deploys on push to main
• Source: GitHub Pages configured with "GitHub Actions" as the source
• Base URL: /pulp/ (served under the user-level custom domain)
• Branch badge: the site header shows which branch the docs were built from

The site generator (tools/build-docs.py) is stdlib-only Python — no pip dependencies. It reads docs-index.yaml for navigation and converts Markdown to HTML.

Adding a New Doc #

1. Create the .md file in the appropriate docs/ subdirectory
2. Add an entry to docs/status/docs-index.yaml with slug, path, kind, and summary
3. Run tools/check-docs.sh to verify
4. If the doc covers a capability, module, or example, update the relevant manifests too