Skip to content

griffe-format-warning

Part of: Griffe Check
Check griffe
Category recommended
Applies to any symbol
Since v1.0.0

Docstring format issue that would break mkdocs rendering

What it detects

This rule flags docstrings with formatting issues caught by griffe's parser that would break rendering in mkdocs documentation sites. This includes malformed section headers, incorrect indentation, and other structural problems.

Why is this a problem?

Formatting issues cause griffe parser warnings during mkdocs build, and the resulting documentation renders incorrectly or incompletely. Visitors to your docs site see broken layouts, missing sections, or garbled text instead of clean API documentation.

How to Fix

Fix the formatting issue identified by griffe's parser. Common fixes include:

  • Indent section entries by 4 spaces under the section header
  • Use the exact section header format (e.g., Args: not Arguments:)
  • Ensure a blank line between sections

Example

def transform(data: list[dict]) -> list[dict]:
    """Transform input data.

    Args:
    data: The input data to transform.

    Returns:
        Transformed data.
    """
    ...

def transform(data: list[dict]) -> list[dict]:
    """Transform input data.

    Args:
        data: The input data to transform.

    Returns:
        Transformed data.
    """
    ...