pydocstyle D103: Missing docstring in public function

Not specified by the original author.

TL;DR: Add a docstring as the first statement inside the function. D103 means a public function has no docstring. Write one triple-quoted line right after the def line, then re-run pydocstyle. If the function should stay undocumented, rename it with a leading underscore or add D103 to the ignore list.

D103: Missing docstring in public function

1. Reproduce:

   pydocstyle path/to/module.py

   Expected: lines like path/to/module.py:12: D103: Missing docstring in public function.

2. Add the docstring inside each flagged function:

   def build_index(pages):
       """Build the search index from a list of pages."""
       ...

3. Re-run:

   pydocstyle path/to/module.py

   Expected: no D103 lines remain.

4. To silence project-wide instead, add to setup.cfg:

   [pydocstyle]
   ignore = D103

Use this when

• pydocstyle reports D103 on functions
• CI fails the docs-lint step with missing-docstring codes
• You are documenting a codebase function by function

Not for this skill when

• The missing docstring is on a module or class - those are D100 and D101
• The function is private (leading underscore) - pydocstyle already skips it
• The function is a test helper where docstrings add no value - prefer the ignore list over noise docstrings

Variant phrasings

• "pydocstyle D103"
• "Missing docstring in public function"
• "pydocstyle missing function docstring"

Why it happens

pydocstyle treats every function without a leading underscore as public, and its conventions require public functions to carry a docstring. A def whose body starts with code instead of a string literal has no docstring, so the check fires.

Edge cases

• Decorated functions are still checked; the docstring goes inside the def, below the decorators.
• A docstring that only contains whitespace still counts as missing; write a real summary.
• Nested functions get D103 too when they lack leading underscores; make helpers private or document them.

Provenance

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

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

Thread query: pydocstyle "D103: Missing docstring in public function"

TL;DR:

Not specified by the original author.

TL;DR: Add a module docstring as the first statement in the file. D100 means a public module has no docstring. Write one triple-quoted summary at the very top of the file (after any shebang or encoding comment), then re-run pydocstyle. If the module should stay undocumented, rename it with a leading underscore or add D100 to the ignore list.

D100: Missing docstring in public module

1. Reproduce:

   pydocstyle path/to/module.py

   Expected: path/to/module.py:1: D100: Missing docstring in public module.

2. Add the docstring as the first statement in the file:

   """Utilities for rendering the docs sitemap."""
   
   import os

3. Re-run:

   pydocstyle path/to/module.py

   Expected: no output, which means the file is clean.

4. If the module is intentionally undocumented (a script entry point, a test helper), silence the rule in setup.cfg instead:

   [pydocstyle]
   ignore = D100

Use this when

• pydocstyle reports D100 on a module file
• CI fails the docs-lint step with missing-docstring codes
• You are bringing a legacy codebase up to docstring conventions

Not for this skill when

• The missing docstring is on a function or class - those are D103 and D101, different fixes
• The file is a private module (leading underscore) - pydocstyle already skips it
• You use a different docstring linter - the code letters differ per tool

Variant phrasings

• "pydocstyle D100"
• "Missing docstring in public module"
• "pydocstyle missing module docstring"

Why it happens

pydocstyle treats every module without a leading underscore as public API surface, and public surface needs a docstring under its conventions. A file that starts directly with imports or code has no docstring statement, so the check fires on line 1.

Edge cases

• The docstring must be a bare string expression, not assigned to a variable; a lone triple-quoted string on its own line is what counts.
• __init__.py files are modules too and get D100 when they have no docstring.
• A shebang or encoding comment may precede the docstring, but nothing else can.

Provenance

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

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

Thread query: pydocstyle "D100: Missing docstring in public module"

TL;DR:

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.