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.

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.