feat: Support auto docstring style (infer from docstring)

Author: pawamoy

docs/insiders/changelog.md

@@ -2,6 +2,21 @@
 
 ## Griffe Insiders
 
+[](){#insiders-1.3.1}
+### 1.3.1 <small>December 31, 2024</small> { id="1.3.1" }
+
+- Accept per-style docstring options instead of generic options when docstring style is set to `auto`.
+    In MkDocs, apply the following change:
+
+    ```diff
+     docstring_style: auto
+     docstring_options:
+    -  ignore_init_summary: true
+    +  per_style_options:
+    +    google:
+    +      ignore_init_summary: true
+    ```
+
 [](){#insiders-1.3.0}
 
 ### 1.3.0 <small>August 09, 2024</small> { id="1.3.0" }

docs/reference/api/docstrings/parsers.md

@@ -24,6 +24,10 @@
 
 ::: griffe.SphinxOptions
 
+::: griffe.AutoOptions
+
+::: griffe.PerStyleOptions
+
 ## **Advanced API**
 
 ::: griffe.Parser

mkdocs.yml

@@ -229,8 +229,10 @@ plugins:
         options:
           backlinks: tree
           docstring_options:
-            ignore_init_summary: true
-          docstring_style: google
+            per_style_options:
+              google:
+                ignore_init_summary: true
+          docstring_style: auto
           docstring_section_style: list
           extensions:
           - griffe_inherited_docstrings

src/griffe/__init__.py

@@ -206,6 +206,13 @@
     ReturnChangedTypeBreakage,
     find_breaking_changes,
 )
+from griffe._internal.docstrings.auto import (
+    AutoOptions,
+    DocstringDetectionMethod,
+    PerStyleOptions,
+    infer_docstring_style,
+    parse_auto,
+)
 from griffe._internal.docstrings.google import GoogleOptions, parse_google
 from griffe._internal.docstrings.models import (
     DocstringAdmonition,
@@ -245,12 +252,9 @@
 )
 from griffe._internal.docstrings.numpy import NumpyOptions, parse_numpy
 from griffe._internal.docstrings.parsers import (
-    DocstringDetectionMethod,
     DocstringOptions,
     DocstringStyle,
-    infer_docstring_style,
     parse,
-    parse_auto,
     parsers,
 )
 from griffe._internal.docstrings.sphinx import SphinxOptions, parse_sphinx
@@ -409,6 +413,7 @@ def __getattr__(name: str) -> Any:
     "Attribute",
     "AttributeChangedTypeBreakage",
     "AttributeChangedValueBreakage",
+    "AutoOptions",
     "Breakage",
     "BreakageKind",
     "BuiltinModuleError",
@@ -539,6 +544,7 @@ def __getattr__(name: str) -> Any:
     "Parameters",
     "ParametersType",
     "Parser",
+    "PerStyleOptions",
     "ReturnChangedTypeBreakage",
     "RootNodeError",
     "SerializationMixin",

src/griffe/_internal/docstrings/auto.py

@@ -0,0 +1,255 @@
+# This module defines functions to parse docstrings by guessing their style.
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
+from warnings import warn
+
+from griffe._internal.enumerations import Parser
+
+if TYPE_CHECKING:
+    from griffe._internal.docstrings.google import GoogleOptions
+    from griffe._internal.docstrings.models import DocstringSection
+    from griffe._internal.docstrings.numpy import NumpyOptions
+    from griffe._internal.docstrings.parsers import DocstringStyle
+    from griffe._internal.docstrings.sphinx import SphinxOptions
+    from griffe._internal.models import Docstring
+
+
+# This is not our preferred order, but the safest order for proper detection
+# using heuristics. Indeed, Google style sections sometimes appear in otherwise
+# plain markup docstrings, which could lead to false positives. Same for Numpy
+# sections, whose syntax is regular rST markup, and which can therefore appear
+# in plain markup docstrings too, even more often than Google sections.
+_default_style_order = [Parser.sphinx, Parser.google, Parser.numpy]
+
+
+DocstringDetectionMethod = Literal["heuristics", "max_sections"]
+"""The supported methods to infer docstring styles."""
+
+
+_patterns = {
+    Parser.google: (
+        r"\n[ \t]*{0}:([ \t]+.+)?\n[ \t]+.+",
+        [
+            "args",
+            "arguments",
+            "params",
+            "parameters",
+            "keyword args",
+            "keyword arguments",
+            "other args",
+            "other arguments",
+            "other params",
+            "other parameters",
+            "raises",
+            "exceptions",
+            "returns",
+            "yields",
+            "receives",
+            "examples",
+            "attributes",
+            "functions",
+            "methods",
+            "classes",
+            "modules",
+            "warns",
+            "warnings",
+        ],
+    ),
+    Parser.numpy: (
+        r"\n[ \t]*{0}\n[ \t]*---+\n",
+        [
+            "deprecated",
+            "parameters",
+            "other parameters",
+            "returns",
+            "yields",
+            "receives",
+            "raises",
+            "warns",
+            # "examples",
+            "attributes",
+            "functions",
+            "methods",
+            "classes",
+            "modules",
+        ],
+    ),
+    Parser.sphinx: (
+        r"\n[ \t]*:{0}([ \t]+\w+)*:([ \t]+.+)?\n",
+        [
+            "param",
+            "parameter",
+            "arg",
+            "argument",
+            "key",
+            "keyword",
+            "type",
+            "var",
+            "ivar",
+            "cvar",
+            "vartype",
+            "returns",
+            "return",
+            "rtype",
+            "raises",
+            "raise",
+            "except",
+            "exception",
+        ],
+    ),
+}
+
+
+class PerStyleOptions(TypedDict, total=False):
+    """Per-style options for docstring parsing."""
+
+    google: GoogleOptions
+    """Options for Google-style docstrings."""
+    numpy: NumpyOptions
+    """Options for Numpy-style docstrings."""
+    sphinx: SphinxOptions
+    """Options for Sphinx-style docstrings."""
+
+
+def infer_docstring_style(
+    docstring: Docstring,
+    *,
+    method: DocstringDetectionMethod = "heuristics",
+    style_order: list[Parser] | list[DocstringStyle] | None = None,
+    default: Parser | DocstringStyle | None = None,
+    per_style_options: PerStyleOptions | None = None,
+    # YORE: Bump 2: Remove line.
+    **options: Any,
+) -> tuple[Parser | None, list[DocstringSection] | None]:
+    """Infer the parser to use for the docstring.
+
+    [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../../insiders/index.md){ .insiders } —
+    [:octicons-tag-24: Insiders 1.3.0](../../../insiders/changelog.md#1.3.0).
+
+    The 'heuristics' method uses regular expressions. The 'max_sections' method
+    parses the docstring with all parsers specified in `style_order` and returns
+    the one who parsed the most sections.
+
+    If heuristics fail, the `default` parser is returned. If multiple parsers
+    parsed the same number of sections, `style_order` is used to decide which
+    one to return. The `default` parser is never used with the 'max_sections' method.
+
+    For non-Insiders versions, `default` is returned if specified, else the first
+    parser in `style_order` is returned. If `style_order` is not specified,
+    `None` is returned.
+
+    Additional options are parsed to the detected parser, if any.
+
+    Parameters:
+        docstring: The docstring to parse.
+        method: The method to use to infer the parser.
+        style_order: The order of the styles to try when inferring the parser.
+        default: The default parser to use if the inference fails.
+        per_style_options: Additional parsing options per style.
+        **options: Deprecated. Use `per_style_options` instead.
+
+    Returns:
+        The inferred parser, and optionally parsed sections (when method is 'max_sections').
+    """
+    from griffe._internal.docstrings.parsers import parsers  # noqa: PLC0415
+
+    # YORE: Bump 2: Replace block with `per_style_options = per_style_options or {}`.
+    if options:
+        if per_style_options:
+            raise ValueError("Cannot use both `options` and `per_style_options`.")
+        warn("`**options` is deprecated. Use `per_style_options` instead.", DeprecationWarning, stacklevel=2)
+        per_style_options = {"google": options, "numpy": options, "sphinx": options}  # type: ignore[typeddict-item]
+    elif not per_style_options:
+        per_style_options = {}
+
+    style_order = [Parser(style) if isinstance(style, str) else style for style in style_order or _default_style_order]
+
+    if method == "heuristics":
+        for style in style_order:
+            pattern, replacements = _patterns[style]
+            patterns = [
+                re.compile(pattern.format(replacement), re.IGNORECASE | re.MULTILINE) for replacement in replacements
+            ]
+            if any(pattern.search(docstring.value) for pattern in patterns):
+                return style, None
+        return default if default is None or isinstance(default, Parser) else Parser(default), None
+
+    if method == "max_sections":
+        style_sections = {}
+        for style in style_order:
+            style_sections[style] = parsers[style](docstring, **per_style_options.get(style, {}))  # type: ignore[arg-type]
+        style_lengths = {style: len(section) for style, section in style_sections.items()}
+        max_sections = max(style_lengths.values())
+        for style in style_order:
+            if style_lengths[style] == max_sections:
+                return style, style_sections[style]
+
+    raise ValueError(f"Invalid method '{method}'.")
+
+
+class AutoOptions(TypedDict, total=False):
+    """Options for Auto-style docstrings."""
+
+    method: DocstringDetectionMethod
+    """The method to use to infer the parser."""
+    style_order: list[Parser] | list[DocstringStyle] | None
+    """The order of styles to try when inferring the parser."""
+    default: Parser | DocstringStyle | None
+    """The default parser to use if the inference fails."""
+    per_style_options: PerStyleOptions | None
+    """Additional parsing options per style."""
+
+
+def parse_auto(
+    docstring: Docstring,
+    *,
+    method: DocstringDetectionMethod = "heuristics",
+    style_order: list[Parser] | list[DocstringStyle] | None = None,
+    default: Parser | DocstringStyle | None = None,
+    per_style_options: PerStyleOptions | None = None,
+    # YORE: Bump 2: Remove line.
+    **options: Any,
+) -> list[DocstringSection]:
+    """Parse a docstring by automatically detecting the style it uses.
+
+    [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../../insiders/index.md){ .insiders } —
+    [:octicons-tag-24: Insiders 1.3.0](../../../insiders/changelog.md#1.3.0).
+
+    See [`infer_docstring_style`][griffe.infer_docstring_style] for more information
+    on the available parameters.
+
+    Parameters:
+        docstring: The docstring to parse.
+        method: The method to use to infer the parser.
+        style_order: The order of the styles to try when inferring the parser.
+        default: The default parser to use if the inference fails.
+        per_style_options: Additional parsing options per style.
+        **options: Deprecated. Use `per_style_options` instead.
+
+    Returns:
+        A list of docstring sections.
+    """
+    from griffe._internal.docstrings.parsers import parse  # noqa: PLC0415
+
+    # YORE: Bump 2: Replace block with `per_style_options = per_style_options or {}`.
+    if options:
+        if per_style_options:
+            raise ValueError("Cannot use both `options` and `per_style_options`.")
+        warn("`**options` are deprecated. Use `per_style_options` instead.", DeprecationWarning, stacklevel=2)
+        per_style_options = {"google": options, "numpy": options, "sphinx": options}  # type: ignore[typeddict-item]
+    elif not per_style_options:
+        per_style_options = {}
+
+    style, sections = infer_docstring_style(
+        docstring,
+        method=method,
+        style_order=style_order,
+        default=default,
+        per_style_options=per_style_options,
+    )
+    if sections is None:
+        return parse(docstring, style, **per_style_options.get(style, {}))  # type: ignore[arg-type,typeddict-item]
+    return sections