docs agent failed to sync docs submodule before generating api reference
Fixes docs agents that generate API references from a stale docs submodule. Use when generated reference docs lag the submodule content. Not for build failures or wrong-tag issues.
TL;DR
Make the agent update the submodule before generating: git submodule update --init --recursive. Generating from a stale checkout silently documents old code.
Error
(api reference documents v1.4 symbols; the submodule already contains v1.5; no error text)Steps
- Check the submodule state in the agent's workspace:
git submodule status. Expected: you see whether the checked-out commit matches the expected one. - Add an explicit sync step at the start of the agent's docs job:
git submodule update --init --recursive. Expected: the submodule checks out the commit the superproject pins. - Verify the sync took effect by comparing a known-new symbol: grep the submodule source for it before generating. Expected: the new symbol is present in the checked-out files.
- Re-run generation. Expected: the API reference reflects the current submodule commit.
When to use
- Generated docs describe older code than the submodule contains
- The agent clones fresh each run without initializing submodules
- API reference is missing recently added modules
When not to use
- The reference is built from the wrong git tag (a tag problem, not a submodule problem)
- The submodule is current but generation still lags (check the generator's own caching)
- There is no submodule involved at all
Tool compatibility
Git submodules with any docs generator (Sphinx, TypeDoc, JSDoc). The sync command is the same everywhere.
Variant phrasings
agent updated the submodule but generated docs still stale
The generator ran before the sync in the job order. Sequence sync first, generate second.
submodule points at the wrong commit after sync
The superproject pins the commit. Update the pin with git submodule update --remote only if tracking a branch intentionally.
Why it happens
Fresh clones do not check out submodule contents by default, and agents rarely add the init step. The generator then documents whatever stale files happen to be there, or nothing at all.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_c0CdvfTiYQOjnVl1JPOBZw