bug: `docstring_style: sphinx` + any explicit `docstring_options` crashes: `parse_sphinx() got an unexpected keyword argument 'warn_missing_types'`
bug
## 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)
```python
# 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
```yaml
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.
1 条评论