Function _docstring_sections

tools/crocodocs/src/crocodocs/griffe_extract_script.py:214–324

Parse a Griffe docstring into a list of structured section dicts. Each dict has a 'kind' key ('text', 'parameters', 'returns', 'raises', 'admonition') plus kind-specific fields. Returns an empty list when griffe is unavailable or the object has no docstring.

(obj: Any)

def _docstring_sections(obj: Any) -> list[dict[str, Any]]:
    """Parse a Griffe docstring into a list of structured section dicts.

    Each dict has a 'kind' key ('text', 'parameters', 'returns', 'raises', 'admonition')
    plus kind-specific fields. Returns an empty list when griffe is unavailable or the
    object has no docstring.
    """
    try:
        from griffe import (
            DocstringSectionAdmonition,
            DocstringSectionParameters,
            DocstringSectionRaises,
            DocstringSectionReturns,
            DocstringSectionText,
        )
    except Exception:  # pragma: no cover
        return []

    docstring = getattr(obj, "docstring", None)
    if docstring is None:
        return []

    parameter_lookup = _parameter_lookup(obj)
    sections: list[dict[str, Any]] = []
    for section in docstring.parsed:
        if isinstance(section, DocstringSectionText):
            value = getattr(section, "value", None)
            if isinstance(value, str) and value.strip():
                sections.append({"kind": "text", "value": value})
        elif isinstance(section, DocstringSectionParameters):
            items = []
            for item in getattr(section, "value", []) or []:
                parameter = parameter_lookup.get(getattr(item, "name", ""))
                default = getattr(item, "value", None)
                if default is None and parameter is not None:
                    default = getattr(parameter, "default", None)
                items.append(
                    {
                        "name": getattr(item, "name", "") or "",
                        "type": _annotation_to_text(
                            getattr(item, "annotation", None)
                            or getattr(parameter, "annotation", None)
                            if parameter
                            else None
                        ),
                        "default": _annotation_to_text(default),
                        "description": getattr(item, "description", None) or None,
                    }
                )
            if items:
                sections.append({"kind": "parameters", "items": items})
        elif isinstance(section, DocstringSectionReturns):
            items = []
            for item in getattr(section, "value", []) or []:
                items.append(
                    {
                        "name": getattr(item, "name", "") or "",
                        "type": _annotation_to_text(getattr(item, "annotation", None)),