Function parse_google_docstring

docsv/scripts/generate-api-docs.py:104–178

Parse a Google-style docstring into structured sections. Args: docstring: The raw docstring text Returns: Dictionary with keys: description, args, returns, raises, examples, note

(docstring: str)

def parse_google_docstring(docstring: str) -> dict[str, Any]:
    """Parse a Google-style docstring into structured sections.

    Args:
        docstring: The raw docstring text

    Returns:
        Dictionary with keys: description, args, returns, raises, examples, note
    """
    if not docstring:
        return {}

    # Clean the docstring
    cleaned = inspect.cleandoc(docstring)

    # Initialize sections
    sections = {
        "description": "",
        "args": [],
        "returns": "",
        "raises": [],
        "examples": "",
        "note": "",
    }

    # Split into sections based on Google-style headers
    # Match "Args:", "Returns:", "Raises:", "Examples:", "Note:", etc.
    section_pattern = r"^(Args?|Returns?|Raises?|Examples?|Note):\s*$"

    lines = cleaned.split("\n")
    current_section = "description"
    current_content = []

    for line in lines:
        # Check if this line is a section header
        match = re.match(section_pattern, line.strip())
        if match:
            # Save previous section content
            if current_section == "description":
                sections["description"] = clean_rst_markup(
                    "\n".join(current_content).strip()
                )
            elif current_section in ("args", "raises"):
                # Parse parameter list
                sections[current_section] = parse_param_list("\n".join(current_content))
            elif current_section in ("returns", "examples", "note"):
                sections[current_section] = clean_rst_markup(
                    "\n".join(current_content).strip()
                )

            # Start new section
            current_section = (
                match.group(1).lower().rstrip("s")
            )  # Normalize to singular
            if current_section == "arg":
                current_section = "args"
            elif current_section == "return":
                current_section = "returns"