fix: Don't pass unsupported options to Griffe parsers

Issue-337: #337

Author: pawamoy

src/mkdocstrings_handlers/python/_internal/handler.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 import glob
+import inspect
 import os
 import posixpath
 import sys
 from contextlib import suppress
 from dataclasses import asdict
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar
+from typing import TYPE_CHECKING, Any, BinaryIO, Callable, ClassVar
 
 from griffe import (
     AliasResolutionError,
@@ -18,6 +19,10 @@
     ModulesCollection,
     Parser,
     load_extensions,
+    parse_auto,
+    parse_google,
+    parse_numpy,
+    parse_sphinx,
     patch_loggers,
 )
 from mkdocs.exceptions import PluginError
@@ -54,6 +59,34 @@ def chdir(path: str) -> Iterator[None]:
 
 patch_loggers(get_logger)
 
+_PARSER_FUNCTIONS: dict[Parser, Callable] = {
+    Parser.auto: parse_auto,
+    Parser.google: parse_google,
+    Parser.numpy: parse_numpy,
+    Parser.sphinx: parse_sphinx,
+}
+
+
+def _filter_parser_options(parser: Parser | None, options: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Filter options unsupported by the selected Griffe parser."""
+    if parser is None or options is None:
+        return options
+
+    accepted_options = set(inspect.signature(_PARSER_FUNCTIONS[parser]).parameters) - {"docstring"}
+    filtered_options = {}
+    for name, value in options.items():
+        if name in accepted_options:
+            if parser is Parser.auto and name == "per_style_options":
+                filtered_options[name] = {
+                    style: _filter_parser_options(Parser(style), style_options)
+                    for style, style_options in value.items()
+                }
+            else:
+                filtered_options[name] = value
+        else:
+            _logger.warning(f"Ignoring unsupported {parser.value} docstring parser option: {name}")
+    return filtered_options
+
 
 class PythonHandler(BaseHandler):
     """The Python handler class."""
@@ -195,7 +228,10 @@ def collect(self, identifier: str, options: PythonOptions) -> CollectorItem:
 
         parser_name = options.docstring_style
         parser = parser_name and Parser(parser_name)
-        parser_options = options.docstring_options and asdict(options.docstring_options)
+        parser_options = options.docstring_options
+        if parser_options is not None:
+            parser_options = asdict(parser_options)
+            parser_options = _filter_parser_options(parser, parser_options)
 
         if unknown_module:
             extensions = self.normalize_extension_paths(options.extensions)

tests/test_config.py

@@ -0,0 +1,61 @@
+"""Tests for configuration options."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import asdict, fields
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from griffe import Parser, parse_google, parse_numpy, parse_sphinx
+
+from mkdocstrings_handlers.python import AutoStyleOptions, GoogleStyleOptions, NumpyStyleOptions, SphinxStyleOptions
+from mkdocstrings_handlers.python._internal.handler import _filter_parser_options
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@pytest.mark.parametrize(
+    ("options_class", "parser"),
+    [
+        (GoogleStyleOptions, parse_google),
+        (NumpyStyleOptions, parse_numpy),
+        (SphinxStyleOptions, parse_sphinx),
+    ],
+)
+def test_style_options_match_griffe_parser(options_class: type[Any], parser: Callable[..., object]) -> None:
+    """Ensure style options stay in sync with Griffe parser options."""
+    option_names = {field.name for field in fields(options_class)}
+    parser_parameters = inspect.signature(parser).parameters
+    parser_option_names = set(parser_parameters) - {"docstring"}
+
+    assert parser_option_names <= option_names
+
+
+def test_filter_style_options(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure unsupported options are not passed to Griffe and are reported."""
+    options = asdict(SphinxStyleOptions())
+
+    filtered_options = _filter_parser_options(Parser.sphinx, options)
+
+    assert filtered_options == {
+        name: value for name, value in options.items() if name in inspect.signature(parse_sphinx).parameters
+    }
+    assert "warn_missing_types" in options
+    for name in set(options) - set(filtered_options or {}):
+        assert f"Ignoring unsupported sphinx docstring parser option: {name}" in caplog.text
+
+
+def test_filter_auto_style_options(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure unsupported options nested in auto style options are reported."""
+    options = asdict(AutoStyleOptions())
+
+    filtered_options = _filter_parser_options(Parser.auto, options)
+
+    assert filtered_options is not None
+    if "warn_missing_types" in inspect.signature(parse_sphinx).parameters:
+        assert "warn_missing_types" in filtered_options["per_style_options"]["sphinx"]
+    else:
+        assert "warn_missing_types" not in filtered_options["per_style_options"]["sphinx"]
+        assert "Ignoring unsupported sphinx docstring parser option: warn_missing_types" in caplog.text