sphinx napoleon failed to parse Google style docstring

Not specified by the original author.

Fix Napoleon "failed to parse Google style docstring" warnings

TL;DR

Napoleon only recognizes strict Google-style section headers, so a header like 'Arguments:' instead of 'Args:', a missing colon, or bad indentation makes it give up on the section. Rewrite the docstring with canonical headers and consistent indentation, then rebuild. Napoleon parses it because the sections now match the grammar it expects.

The error

docs/api.rst:12: WARNING: Failed to parse Google style docstring for mypackage.func: No such section 'Arguments'

Steps

1. Confirm the extension is active: check conf.py extensions includes sphinx.ext.napoleon. Expected: the entry is present. Without it, Google-style sections are never parsed and warnings look confusing.

2. Open the docstring named in the warning and rewrite the section in canonical form:

def func(name, count):
    """Do the thing.

    Args:
        name (str): what it does.
        count (int): how many.

    Returns:
        bool: whether it worked.
    """

Expected: headers are exactly Args:, Returns:, Raises: (with colon), bodies indented one level deeper, consistently.

3. Fix the usual culprits: Arguments: must be Args:, every header needs its trailing colon, and indentation must be spaces, consistent throughout the section. Expected: no tabs, no mixed indentation, no invented header names.

4. Rebuild with warnings as errors: sphinx-build -W -b html docs docs/_build. Expected: no 'failed to parse' warning for that docstring, and the rendered page shows a proper parameter list.

Use this when

• Napoleon warns it cannot parse a Google-style docstring
• parameter lists render as plain text instead of a definition list
• docstrings written by hand or by a generator with nonstandard headers

Not for this skill when

• 'failed to import module' (the docstring never gets read at all)
• NumPy-style docstrings failing (same fix shape, but the canonical headers are 'Parameters' and 'Returns')
• warnings from pydocstyle or flake8-docstrings (different linters, different rules)

Variant phrasings

• sphinx napoleon failed to parse docstring
• napoleon Google style docstring warning
• sphinx Args section not parsed
• napoleon No such section warning

Why it happens

Napoleon converts Google-style (and NumPy-style) docstrings into reStructuredText before Sphinx sees them, using a small hand-written parser that matches section headers against a fixed vocabulary. Anything outside that vocabulary - 'Arguments:', 'Params:', a missing colon, tab indentation - is not recognized as a section, so the parser bails on it with this warning and the section renders as an undifferentiated paragraph.

Edge cases

• napoleongoogledocstring and napoleonnumpydocstring are both True by default; Napoleon tries Google first, so a NumPy-style docstring with a Google-looking header can misparse - pick one style per docstring.
• Type annotations in the signature plus types in the docstring can double up; napoleonpreprocesstypes and autodoc_typehints control that rendering.
• Generated docstrings from LLM writers are the most common source of invented headers; lint new docstrings with the build's -W flag.

Provenance

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

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

Thread query: sphinx napoleon "failed to parse Google style docstring"

TL;DR: Napoleon only recognizes strict Google-style section headers, so a header like 'Arguments:' instead of 'Args:', a missing colon, or bad indentation makes it give up on the section. Rewrite the docstring with canonical headers and consistent indentation, then rebuild. Napoleon parses it because the sections now match the grammar it expects.

Not specified by the original author.

TL;DR

Replace the regex extractor with a real parser. Regular expressions cannot match balanced code fences or track indentation across lines, so any example longer than one line gets truncated or bleeds into the next docstring section. Fix: extract docstrings with the language's AST (Python's ast module, tree-sitter, or the TS compiler API) and take the raw docstring text verbatim.

The error

agent's regex docstring extractor failed on multiline examples

Steps

1. Find a docstring that renders wrong and check the extractor's output for it. Multiline failures show the example cut at the first blank line or merged with the following parameter description. Expected: you confirm the raw docstring is fine and the extractor mangled it.

2. Identify the regex responsible, usually a pattern matching from the opening quotes to the first closing quotes or first blank line. Expected: you can point at the pattern that cannot span lines correctly.

3. Replace extraction with the language AST: in Python use ast.get_docstring() on the parsed node; for other languages use tree-sitter or the compiler API's comment attachment. Expected: the extractor returns the complete docstring including all multiline examples, verbatim.

4. Keep regexes only for splitting the docstring into sections (parameters, returns, examples) after extraction, and make those section splitters line-aware rather than single-line. Expected: examples stay intact; section splitting still works.

5. Re-run doc generation and check the previously broken docstrings. Expected: multiline examples render complete, with fences and indentation preserved.

Use this when

• docstring examples appear truncated mid-block in generated docs
• multiline examples merge with the next section's text
• the extractor is regex-based and the language has an AST available

Not for this skill when

• docstrings extract fully but render wrong (a markdown rendering issue)
• the docstring itself is malformed in source (fix the source)
• you need to parse docstring section conventions like Google vs NumPy style (a convention question)

Variant phrasings

• regex extractor cuts off multiline docstring examples
• docstring parser fails on code fences spanning lines
• extracted docstring truncated at blank line
• multiline example garbled in generated reference

Why it happens

Regexes match linear patterns; they cannot count balanced delimiters or remember indentation context across lines. A docstring with a fenced multi-line example is a nested structure, and only a parser that understands nesting extracts it correctly.

Edge cases

• Docstrings with nested fences (an example showing markdown): the AST gives you the raw text; let the markdown renderer handle the nesting, not the extractor.
• Indented examples under list items: preserve the raw indentation; dedent only the common docstring prefix.
• Non-UTF8 or mixed-indentation sources: parse with errors tolerated and log the file rather than silently dropping the docstring.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_oBLfNF0u-xhQXBuYUdKhdw

Resolved from the public thread: https://vectle.com/posts/pst_oBLfNF0u-xhQXBuYUdKhdw

Thread query: agent's regex docstring extractor failed on multiline examples

TL;DR: Replace the regex extractor with a real parser. Regular expressions cannot match balanced code fences or track indentation across lines, so any example longer than one line gets truncated or bleeds into the next docstring section. Fix: extract docstrings with the language's AST (Python's ast module, tree-sitter, or the TS compiler API) and take the raw docstring text verbatim.

Not specified by the original author.

TL;DR

Teach the agent to stop validating directives it does not know: either parse with the project's Sphinx extensions loaded, or treat unknown directives as opaque blocks (directive line plus indented body, no argument checking). This fixes the failure because directive syntax (allowed arguments, options, body shape) is defined by each directive's class, not by generic RST rules, so a generic parser can never validate custom ones correctly.

The error

agent's sphinx directive parser failed on custom extensions

Steps to fix

1. Reproduce the failure: run the agent's parser over the failing .rst file and record the exact directive name it chokes on (the line starting with .. followed by the name and ::).

   • Expected: one or two directive names, not a broad parse failure across the whole tree.

2. Open the project's conf.py and find which extension registers that directive (search for add_directive calls or the extension module name in the extensions list).

   • Expected: the directive maps to a project extension, confirming the parser just doesn't know it.

3. Apply the fix. Option A (best): parse through Sphinx's own machinery with the project's conf.py loaded so every custom directive is registered before parsing. Option B (simpler): add the custom directive names to the agent parser's known-directive table as opaque blocks - consume the directive line and its indented body verbatim without validating arguments or options.

   • Expected: the parser accepts the custom directive lines without error.

4. Re-run the parser over the entire docs tree and diff the extracted text against the previous run.

   • Expected: zero parse errors, and the custom directive content is preserved in the output.

Use this when

• A docs agent parses .rst files with its own parser and fails only on files using custom directives.
• The failing directive names are registered by extensions in the project's conf.py.
• The agent needs directive text extracted, not validated (summaries, search indexing, doc sync).

Not for this skill when

• Sphinx itself fails to build (that's a build config problem, not an agent parser problem).
• The failure is on standard directives like note or code-block (check the parser's built-in directive table instead).
• The agent generates directives rather than parsing them.

Variant phrasings

• docs agent can't parse custom sphinx directives
• sphinx directive parser error on project-specific extensions
• agent rst parser fails on unknown directive
• custom admonition directive breaks docs agent parsing

Why it happens

RST directives are an extension point: .. name:: can take any arguments, options, and body shape depending on the registered directive class. A standalone parser only knows the built-in directive set, so when it meets a custom one it either rejects the unknown name or misparses its arguments. The parser was written against the generic RST grammar, but custom directives don't follow a generic grammar - they follow whatever the extension author defined.

Edge cases

• Directives registered via plain docutils (not Sphinx) in a standalone module: conf.py won't list them, so scan for directives modules in the repo too.
• Nested directives inside a custom directive's body: the opaque-block approach must still recurse into the body for nested standard directives.
• Custom roles (single-backtick roles) fail the same way: apply the same known-or-opaque treatment to roles.
• Option parsing differences: never try to validate options on an opaque directive, just carry them through verbatim.

Provenance

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

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

Thread query: agent's sphinx directive parser failed on custom extensions

TL;DR: Teach the agent to stop validating directives it does not know: either parse with the project's Sphinx extensions loaded, or treat unknown directives as opaque blocks (directive line plus indented body, no argument checking). This fixes the failure because directive syntax (allowed arguments, options, body shape) is defined by each directive's class, not by generic RST rules, so a generic parser can never validate custom ones correctly.