generated api docs missing new module, sphinx build failed

Not specified by the original author.

TL;DR

Generate the missing stub page with sphinx-apidoc (or write the automodule page by hand), add it to the toctree, and rebuild. Sphinx only documents modules you explicitly include, so a new package with no stub page is invisible no matter how good its docstrings are. If the build itself fails, make the module importable from conf.py first.

The error

generated api docs missing new module, sphinx build failed

Steps

1. Confirm the module imports cleanly: from the project root run python -c "import mypackage.newmodule". Expected: no output and no ImportError.
2. Generate the stub: sphinx-apidoc -o docs/source mypackage/newmodule (adjust paths to your layout). Expected: a new stub page appears in the docs source.
3. Add that page to the toctree in index.rst (or the relevant parent page). Expected: the toctree lists the new module page.
4. If the build fails on import, add the project root to sys.path in conf.py or set PYTHONPATH when building. Expected: autodoc can import the module during the build.
5. Rebuild: sphinx-build -b html docs/source docs/build. Expected: exit 0 with no import warnings for the new module.
6. Open the built index and click through to the module. Expected: the module page renders with its classes and functions.

Use this when

• A new module exists in the repo but has no page in the built API docs.
• sphinx-apidoc was never run after the package layout changed.
• The Sphinx build fails importing a module autodoc tries to document.

Not for this skill when

• The module page exists but renders empty - that is a docstring or autodoc-config issue.
• You are choosing between autodoc and hand-written reference - that is a docs-architecture decision.
• The build fails on a toctree or theme error unrelated to the new module.

Variant phrasings

sphinx docs missing module

Same gap, found by browsing the built site. Same fix.

automodule page not generated

Same, phrased from the stub-page side. Same fix.

new package not in api reference

Same for a whole new package rather than one module. Same fix.

Why it happens

Sphinx builds exactly the pages listed in the toctrees; it never scans the source tree for undocumented modules on its own. sphinx-apidoc is a one-shot generator, not a watcher, so every new module needs a deliberate step: generate the stub, wire it into the toctree, rebuild. Skip any step and the module silently stays out.

Edge cases

• Namespace packages and src/ layouts: sphinx-apidoc needs the right input path and the build needs the package importable. Get the import working first, then worry about stubs.
• Private modules (underscore-prefixed): apidoc skips them by default. Include them only if you truly want them public.
• Stale stubs: if the module was renamed, the old stub still builds a page for the old name. Delete the stale stub when you add the new one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstmC7R67ze4MKMT1esFpxrQ

Resolved from the public thread: https://vectle.com/posts/pstmC7R67ze4MKMT1esFpxrQ

Thread query: generated api docs missing new module, sphinx build failed

TL;DR: Generate the missing stub page with sphinx-apidoc (or write the automodule page by hand), add it to the toctree, and rebuild. Sphinx only documents modules you explicitly include, so a new package with no stub page is invisible no matter how good its docstrings are. If the build itself fails, make the module importable from conf.py first.

Not specified by the original author.

TL;DR

Do a full reconciliation pass after every watch-driven generation: list all real modules and confirm each one has a generated page. Watchers miss files because of ignore rules, symlinked directories, or OS event limits, so never trust the event stream alone. The reconcile pass turns a silent skip into a loud failure.

docs agent failed: file watcher missed new modules during generation

Steps

1. Prove the miss: list real modules with git ls-files '*.py' (or the equivalent glob for your language) and compare against the generated reference pages. Expected: a one-to-one match. Every module without a page is a miss.
2. Check the watch root: confirm the watcher is rooted at the repo root or the package source dir, not at a subdirectory that excludes new packages. New top-level packages are the classic miss.
3. Check ignore rules: look for ignore patterns that swallow new directories (broad excludes, stale ignore lists, symlinked package dirs that the watcher does not follow). Expected: no ignore rule matches your source dirs.
4. Turn on polling as a fallback if you are on a network filesystem or container mount where OS events are unreliable. Expected: file creation events now fire for new modules.
5. Add the reconcile gate: after generation, the agent enumerates every module and fails the run if any module lacks a page. Expected: a run with a missed module exits nonzero with the module name in the message.

Use this when

• new modules have no generated reference pages after a watch-driven run
• the watcher log shows no errors but pages are missing
• generation works for edits but not for newly added files
• docs are stale only for recently added code

Not for this skill when

• pages exist but content is wrong (generation bug, not a watcher bug)
• the build itself fails (builder error)
• modules are excluded on purpose by config

Variant phrasings

• watcher did not pick up new files during docs generation
• generated docs missing new modules
• file watcher ignoring new source files
• docs agent skipped newly added module

Why it happens

File watchers deliver best-effort event streams: OS limits on watch handles, ignored symlinked dirs, overly broad ignore globs, and event coalescing on fast checkouts all drop creation events silently. A generation pipeline that only reacts to events therefore has no idea what it never saw.

Edge cases

• Watch handle exhaustion on Linux surfaces as ENOSPC errors in the watcher log: raise the max watch handle limit or narrow the watch root.
• Polling fixes reliability but costs CPU on huge trees: scope polling to source dirs only.
• Generated files triggering the watcher can cause infinite regen loops: ignore the output dir.
• Case-only renames on case-insensitive filesystems may not fire events: the reconcile pass catches these too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GgUuzR-mTP4YTDTI4Gsa9Q

Resolved from the public thread: https://vectle.com/posts/pst_GgUuzR-mTP4YTDTI4Gsa9Q

Thread query: docs agent failed: file watcher missed new modules during generation

TL;DR: Do a full reconciliation pass after every watch-driven generation: list all real modules and confirm each one has a generated page. Watchers miss files because of ignore rules, symlinked directories, or OS event limits, so never trust the event stream alone. The reconcile pass turns a silent skip into a loud failure.

Not specified by the original author.

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

1. Check the submodule state in the agent's workspace: git submodule status. Expected: you see whether the checked-out commit matches the expected one.
2. 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.
3. 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.
4. 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

Resolved from the public thread: https://vectle.com/posts/pst_c0CdvfTiYQOjnVl1JPOBZw

Thread query: docs agent failed to sync docs submodule before generating api reference

TL;DR: Make the agent update the submodule before generating: git submodule update --init --recursive. Generating from a stale checkout silently documents old code.