sphinx autodoc ValueError: invalid signature

Not specified by the original author.

TL;DR

Find the callable named just before the traceback, then give autodoc a parseable signature. Unwrap or annotate the decorator, add an explicit signature, or exclude the member. Rebuild and confirm the page renders.

The exact error

ValueError: invalid signature

Steps

1. Identify the callable Read the traceback above the ValueError; autodoc names the module and object it was processing when it failed. Success check: You have the module path and object name of the failing callable.

2. Inspect the signature Import the object in a Python shell and call inspect.signature on it. Decorators that hide wrapped and C functions without _textsignature__ are the usual culprits. Success check: inspect.signature raises the same ValueError, confirming the source.

3. Give it a parseable signature For decorated functions, set functools.wraps or assign wrapped. For dynamic callables, attach an explicit signature object. As a last resort, exclude the member with :exclude-members:. Success check: inspect.signature returns a valid signature and the object imports cleanly.

4. Rebuild the affected page Run sphinx-build -b html on the project and open the rendered API page. Success check: The page renders with the correct parameter list and the build log shows no ValueError.

When to use

• Use when autodoc dies on ValueError: invalid signature during a docs build.
• Use when an agent generates API reference for a codebase with heavy decorators or C extensions.

When not to use

• Not for ImportError or ModuleNotFoundError in autodoc (different failure family).
• Not for signature mismatches between docs and code (that is doc drift, not a build crash).

Why it happens

Autodoc calls inspect.signature on every documented callable. Objects whose signatures are constructed dynamically, hidden by decorators without wrapped, or implemented in C without signature metadata make that call raise ValueError, which aborts the page.

Edge cases

napoleon and autodoc-typehints change how signatures are processed, so a signature that builds under plain autodoc can fail with extensions enabled. Mocking the module with autodocmockimports can hide the real signature; prefer fixing the signature over mocking when the object is importable.

Provenance

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

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

Thread query: sphinx autodoc "ValueError: invalid signature"

TL;DR: Find the callable named just before the traceback, then give autodoc a parseable signature. Unwrap or annotate the decorator, add an explicit signature, or exclude the member. Rebuild and confirm the page renders.

Not specified by the original author.

TL;DR

Lint every generated .rst file with docutils before building: parse it with publish_doctree set to halt on warnings, fix what it flags, then build. LLM writers produce plausible-looking RST with broken directive indentation and missing blank lines. A 2-second lint catches what a 2-minute build failure only hints at.

docs agent's llm writer produced invalid rst, sphinx build failed

Steps

1. Find the offending file: read the sphinx-build error; it names the .rst file and line number. Open that spot. Expected: you can see the malformed markup (bad indent, directive run into text, unknown directive).
2. Lint the file directly: python -c "from docutils.core import publish_doctree; publish_doctree(open('docs/api/broken.rst').read(), settings_overrides={'report_level': 2, 'halt_level': 2})". Expected: it raises on the same problem Sphinx hit, instantly, without a full build.
3. Fix the usual LLM RST mistakes: directives need a blank line before them and their content indented consistently (three spaces is the safe convention); inline markup needs matching delimiters; unknown directives usually mean the writer invented a directive name, replace it with a real one.
4. Re-lint until clean, then run the full sphinx-build. Expected: exit 0 and the page renders.
5. Add the lint as a gate in the agent loop: every generated .rst file is parsed before the build step, and a parse failure fails the run with the file and line. Expected: invalid RST never reaches sphinx-build again.

Use this when

• sphinx-build fails on agent-generated .rst files
• the error names a file the LLM writer produced
• you want a fast pre-build check for generated RST

Not for this skill when

• hand-written RST fails (same lint helps, but the fix is editing, not agent gating)
• the build fails on valid RST (extension or config problem)
• you use Markdown sources instead (lint the Markdown, different tool)

Variant phrasings

• llm generated rst does not build
• sphinx errors on ai-written rst
• invalid restructuredtext from docs agent

Why it happens

LLMs learn RST from rendered examples, not from the spec, so they reproduce the look of directives while getting the whitespace rules wrong: missing blank lines, inconsistent indentation, invented directive names. Sphinx is strict about these, so the build fails on markup that reads fine to a human.

Edge cases

• Plain docutils does not know Sphinx-specific directives: for those, treat Sphinx's own error as the final word.
• A file can parse yet render badly (wrong nesting): spot-check the rendered page for generated files.
• Mixed line endings can confuse the parser: normalize generated files to LF.
• Very long lines from the writer are legal but unreadable: wrap them for future debuggability.

Provenance

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

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

Thread query: docs agent's llm writer produced invalid rst, sphinx build failed

TL;DR: Lint every generated .rst file with docutils before building: parse it with publish_doctree set to halt on warnings, fix what it flags, then build. LLM writers produce plausible-looking RST with broken directive indentation and missing blank lines. A 2-second lint catches what a 2-minute build failure only hints at.

Not specified by the original author.

Fix Sphinx extension "has no setup()" failure for autodoc

TL;DR

Sphinx imported something named like the extension but it was not the real one, almost always a local file or package shadowing sphinx.ext.autodoc, or sphinx-build running from a different Python environment than the one where Sphinx is installed. Remove or rename the shadowing module (or fix the environment), then rebuild. The extension loads because the import now resolves to the real Sphinx package.

The error

Extension error:
Extension 'sphinx.ext.autodoc' has no setup() function.

Steps

1. Check what the name resolves to in the build environment: python -c "import sphinx.ext.autodoc; print(sphinx.ext.autodoc.__file__)" using the same Python that runs sphinx-build. Expected: a path under site-packages. If it prints a path inside your repo, that file is shadowing the real extension.

2. Hunt the shadow: find docs -maxdepth 3 -name "sphinx*" -o -maxdepth 3 -name "autodoc*", and check conf.py for sys.path.insert lines that put your own directories first. Rename or remove the shadowing module or package (e.g. a docs/sphinx/ directory or an autodoc.py helper). Expected: no local module or package named sphinx or autodoc remains on the path conf.py sets up.

3. If the import itself fails in step 1, reinstall: pip install sphinx or pip install --force-reinstall sphinx. Expected: step 1 now prints the site-packages path.

4. Confirm the binary matches the environment: which sphinx-build and the shebang line at the top of that file should point at the same Python you tested. Expected: one Python environment owns both sphinx-build and the installed Sphinx.

5. Rebuild: sphinx-build -b html docs docs/_build. Expected: no 'has no setup()' error; the build proceeds past extension loading.

Use this when

• any Sphinx extension fails with 'has no setup()' (the fix is the same for other extensions)
• the build dies before reading any source files
• you recently added a helper module named sphinx, autodoc, or similar

Not for this skill when

• ModuleNotFoundError for a third-party extension (that means it is not installed at all)
• an ImportError raised inside the extension's own setup() (different failure, read the traceback)
• theme errors like 'no theme named' (theme problem, not extension loading)

Variant phrasings

• sphinx extension has no setup function
• sphinx-build extension error autodoc
• Could not import extension sphinx.ext.autodoc
• sphinx ExtensionError has no setup

Why it happens

When Sphinx loads an extension it imports the module and calls its setup() function. The 'has no setup()' error means the import succeeded but returned the wrong module: Python found your local sphinx.py, sphinx/ package, or autodoc.py before the installed Sphinx because conf.py inserted your directories at the front of sys.path. The other classic cause is two Python environments: sphinx-build from one, Sphinx installed in another.

Edge cases

• A directory named sphinx/ anywhere on sys.path shadows the whole package, not just one module; check for those first.
• Virtualenv mixups are silent: head -1 $(which sphinx-build) shows which interpreter the script uses.
• After renaming a shadowing file, delete stale pycache directories or the old bytecode can still shadow.

Provenance

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

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

Thread query: sphinx-build: extension 'sphinx.ext.autodoc' "has no setup()" failed

TL;DR: Sphinx imported something named like the extension but it was not the real one, almost always a local file or package shadowing sphinx.ext.autodoc, or sphinx-build running from a different Python environment than the one where Sphinx is installed. Remove or rename the shadowing module (or fix the environment), then rebuild. The extension loads because the import now resolves to the real Sphinx package.