DC010: DocstringStyle

Overview

Property Value
ID DC010
Name DocstringStyle
Group documentation
Severity NOTE

Description

Enforces consistent docstring style across the package by detecting mixed usage of Google, NumPy, and Sphinx docstring formats.

Consistent docstring style improves:

  • Readability: Developers know what format to expect
  • Documentation generation: Tools like Sphinx work better with consistent styles
  • Onboarding: New contributors can follow established patterns
  • Code review: Easier to spot style deviations

What it checks

The check scans all Python files in the package and uses AST analysis to detect docstring styles in:

  • Module docstrings
  • Function and method docstrings
  • Class docstrings

Detected styles

Google style:

def function(arg1, arg2):
    """Summary line.

    Args:
        arg1: Description of arg1.
        arg2: Description of arg2.

    Returns:
        Description of return value.

    Raises:
        ValueError: If something is wrong.
    """

NumPy style:

def function(arg1, arg2):
    """Summary line.

    Parameters
    ----------
    arg1 : type
        Description of arg1.
    arg2 : type
        Description of arg2.

    Returns
    -------
    type
        Description of return value.

    Raises
    ------
    ValueError
        If something is wrong.
    """

Sphinx style:

def function(arg1, arg2):
    """Summary line.

    :param arg1: Description of arg1.
    :type arg1: type
    :param arg2: Description of arg2.
    :returns: Description of return value.
    :rtype: type
    :raises ValueError: If something is wrong.
    """

Result states

  • PASSED: All docstrings use a consistent style
  • FAILED: Multiple docstring styles detected, or style doesn’t match enforced style
  • NOT_APPLICABLE: Package not found or no styled docstrings found

How to fix

Choose one style and convert all docstrings

If the check detects mixed styles, convert all docstrings to the dominant style:

# Before (mixed styles)

# File 1: Google style
def function_a(x):
    """Do something.

    Args:
        x: Input value.

    Returns:
        Processed value.
    """

# File 2: NumPy style (inconsistent!)
def function_b(x):
    """Do something else.

    Parameters
    ----------
    x : int
        Input value.

    Returns
    -------
    int
        Processed value.
    """

# After (consistent Google style)

def function_a(x):
    """Do something.

    Args:
        x: Input value.

    Returns:
        Processed value.
    """

def function_b(x):
    """Do something else.

    Args:
        x: Input value.

    Returns:
        Processed value.
    """

Use pydocstyle to enforce style

# Install pydocstyle
pip install pydocstyle

# Check with Google convention
pydocstyle --convention=google src/

# Check with NumPy convention
pydocstyle --convention=numpy src/

Configure in pyproject.toml:

[tool.pydocstyle]
convention = "google"

Use ruff for docstring enforcement

# pyproject.toml
[tool.ruff.lint]
select = ["D"]  # Enable pydocstyle rules

[tool.ruff.lint.pydocstyle]
convention = "google"  # or "numpy"

Use docformatter for auto-formatting

# Install docformatter
pip install docformatter

# Format docstrings in place
docformatter --in-place --recursive src/

Configuration

Enforce a specific style

[tool.pycmdcheck.checks.DC010]
docstring_style = "google"  # or "numpy" or "sphinx"

When a style is enforced, all docstrings must use that style.

Skip this check

[tool.pycmdcheck]
skip = ["DC010"]

CLI

pycmdcheck --skip DC010

Style comparison

Arguments/Parameters

Style Syntax
Google Args: section with name: description
NumPy Parameters section with name : type under dashes
Sphinx :param name: and :type name:

Return values

Style Syntax
Google Returns: section
NumPy Returns section under dashes
Sphinx :returns: and :rtype:

Exceptions

Style Syntax
Google Raises: section
NumPy Raises section under dashes
Sphinx :raises ExceptionType:

Which style to choose?

  • Google style: Most readable, popular in modern Python projects
  • NumPy style: Common in scientific Python (NumPy, SciPy, pandas)
  • Sphinx style: Original Sphinx format, more verbose

Most new projects prefer Google or NumPy style for better readability.

Why NOTE severity?

This check is a NOTE because:

  • Docstring style is a team preference
  • Existing projects may have historical inconsistencies
  • The impact on functionality is minimal

However, consistent style improves:

  • Documentation generation
  • IDE tooltip rendering
  • Code review efficiency

References