bug: `docstring_style: sphinx` + any explicit `docstring_options` crashes: `parse_sphinx() got an unexpected keyword argument 'warn_missing_types'`

[selbs]

Description

With mkdocstrings-python 2.0.5 on griffelib 2.1.0, any configuration that uses docstring_style: sphinx and sets at least one key under docstring_options crashes on the first rendered docstring:

TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types'

Configurations with no docstring_options at all build cleanly, which makes this easy to miss in minimal testing: the empty case short-circuits before the bad kwarg is ever produced.

Mechanism

• SphinxStyleOptions still declares warn_missing_types: bool = True as a defaulted field (mkdocstrings_handlers/python/_internal/config.py:252, class at :240).
• PythonHandler.render builds the parser options via parser_options = options.docstring_options and asdict(options.docstring_options) (handler.py:198). asdict() materializes every field of the dataclass — defaults included — so warn_missing_types=True is emitted as soon as docstring_options is non-empty.
• The dict is assigned to doc_object.docstring.parser_options (handler.py:246) and forwarded by griffe (griffe/_internal/models.py:183: parse(self, parser or self.parser, **(options or self.parser_options))).
• griffelib 2.1.0's parse_sphinx signature is parse_sphinx(docstring, *, warn_unknown_params=True, warnings=True) (griffe/_internal/docstrings/sphinx.py:98) — it no longer accepts warn_missing_types, so the call raises TypeError.

Note the asymmetry: parse_google (google.py:881) still accepts warn_missing_types, so google-style configs are unaffected. Only the sphinx parser dropped the parameter, while SphinxStyleOptions still declares it. (griffelib's internal _read_return helper in sphinx.py still implements the warn_missing_types behavior — the kwarg was dropped from the public parser signature only.)

Minimal reproducer (no mkdocs needed)

# venv: griffelib==2.1.0
from griffe import Docstring, Parser

d = Docstring(
    ":param x: foo",
    parser=Parser.sphinx,
    parser_options={"warn_unknown_params": False, "warn_missing_types": True, "warnings": True},
)
d.parsed
# TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types'

That parser_options dict is byte-for-byte what mkdocstrings-python 2.0.5 produces from the mkdocs config below. The same Docstring with parser_options={} parses fine — the false-negative path.

mkdocs config that triggers it

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: sphinx
            docstring_options:
              warn_unknown_params: false   # any single key here is enough

Full-build traceback (excerpt)

TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types'
  ...
  mkdocstrings/_internal/extension.py:194, in _process_block
    rendered = render(data, options)
  mkdocstrings_handlers/python/_internal/handler.py:264, in render
    return template.render(
  ...templates/material/_base/module.html.jinja:94, in block 'docstring'
  griffe/_internal/models.py:163, in parsed
    return self.parse()
  griffe/_internal/models.py:183, in parse
    return parse(self, parser or self.parser, **(options or self.parser_options))
  griffe/_internal/docstrings/parsers.py:53, in parse
    return parsers(docstring, **options)

The failure is content-independent — it fires on the first docstring rendered, regardless of what the docstring contains, and regardless of any griffe extensions in use.

Environment

• mkdocstrings-python 2.0.5
• griffelib 2.1.0 (sole provider of the griffe import; the legacy griffe 1.x distribution is not installed)
• mkdocstrings 1.0.6
• Python 3.12.13

Suggested fix directions

Any of:

1. Drop warn_missing_types from SphinxStyleOptions in mkdocstrings-python (align the options schema with parse_sphinx's actual signature), or
2. Filter forwarded kwargs per parser signature before assigning parser_options, or
3. Re-accept warn_missing_types in griffelib's parse_sphinx and thread it through — the internal _read_return helper still implements it, so this restores documented behavior rather than adding new surface.

Thank you.

[pawamoy]

Thanks @selbs! Confirmed. I'll do the following:

• surface the warn_missing_types parameter in parse_sphinx since it's useful
• that fixes the situation in mkdocstrings-python
• still, add a test in mkdocstrings-python that assert we don't declare options that griffe parsers don't support
• and filter options before forwarding them to the griffe parser (emitting warnings for those who are not supported)