Use DeepDoc
Keeping docs fresh
How update decides what to regenerate, and how to keep docs current in CI.
After your first generate, update is the command you run. It diffs against
the last commit DeepDoc synced and regenerates only the pages your change
affected.
deepdoc update
What it does
Diff. Compares your working tree against the last synced commit, read
from saved state in .deepdoc/.
Pick a strategy. Either an incremental pass over the affected pages, a full replan, or nothing at all if the diff touched no documented code.
Regenerate. Only the pages in scope. This is where the cost is.
Record. Appends to the changelog, refreshes the sidebar, and saves the new sync point.
If nothing relevant changed, update does nothing and costs nothing.
When it replans everything
Usually update stays incremental. It escalates to a full replan when:
- you pass
--replan - DeepDoc’s own engine version changed — a new release can plan differently, so the previous plan is no longer comparable
- the change is structural enough that the existing plan cannot describe it
Checking before you run
deepdoc status
Shows what has been generated and which pages are now stale. Free, and a good habit before an update in a repository you have not touched for a while.
Diffing against something else
deepdoc update --since v1.4.0
deepdoc update --since HEAD~10
Any git ref works. Useful after a long-lived branch merge, when the last synced commit is not the comparison you want.
In CI
- name: Update documentation
run: deepdoc update --strict-quality
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
--strict-quality exits non-zero when any page comes out invalid, degraded or
a stub — so a bad run fails the job instead of quietly publishing broken pages.
When quality gates block you
deploy refuses to publish docs with unresolved problems:
Refusing to deploy docs with unresolved quality issues:
- invalid docs present: cli-commands
- stub docs present: page-generation-validation
That is the gate doing its job. The pages genuinely did not generate cleanly. Inspect them:
cat .deepdoc/generation_quality.json
Then re-run update for those pages, or generate --force if the whole set
needs redoing.