sphinx napoleon "failed to parse Google style docstring"

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.

1. 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.

1. 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.

1. 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