René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"bug: `docstring_style: sphinx` + any explicit `docstring_options` crashes: `parse_sphinx() got an unexpected keyword argument 'warn_missing_types'`","articleBody":"## Description\n\nWith 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:\n\n```\nTypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types'\n```\n\nConfigurations 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.\n\n## Mechanism\n\n- `SphinxStyleOptions` still declares `warn_missing_types: bool = True` as a defaulted field (`mkdocstrings_handlers/python/_internal/config.py:252`, class at `:240`).\n- `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.\n- 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))`).\n- 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`.\n\nNote 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.)\n\n## Minimal reproducer (no mkdocs needed)\n\n```python\n# venv: griffelib==2.1.0\nfrom griffe import Docstring, Parser\n\nd = Docstring(\n    \":param x: foo\",\n    parser=Parser.sphinx,\n    parser_options={\"warn_unknown_params\": False, \"warn_missing_types\": True, \"warnings\": True},\n)\nd.parsed\n# TypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types'\n```\n\nThat `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.\n\n## mkdocs config that triggers it\n\n```yaml\nplugins:\n  - mkdocstrings:\n      handlers:\n        python:\n          options:\n            docstring_style: sphinx\n            docstring_options:\n              warn_unknown_params: false   # any single key here is enough\n```\n\n## Full-build traceback (excerpt)\n\n```\nTypeError: parse_sphinx() got an unexpected keyword argument 'warn_missing_types'\n  ...\n  mkdocstrings/_internal/extension.py:194, in _process_block\n    rendered = render(data, options)\n  mkdocstrings_handlers/python/_internal/handler.py:264, in render\n    return template.render(\n  ...templates/material/_base/module.html.jinja:94, in block 'docstring'\n  griffe/_internal/models.py:163, in parsed\n    return self.parse()\n  griffe/_internal/models.py:183, in parse\n    return parse(self, parser or self.parser, **(options or self.parser_options))\n  griffe/_internal/docstrings/parsers.py:53, in parse\n    return parsers(docstring, **options)\n```\n\nThe 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.\n\n## Environment\n\n- mkdocstrings-python 2.0.5\n- griffelib 2.1.0 (sole provider of the `griffe` import; the legacy `griffe` 1.x distribution is **not** installed)\n- mkdocstrings 1.0.6\n- Python 3.12.13\n\n## Suggested fix directions\n\nAny of:\n1. Drop `warn_missing_types` from `SphinxStyleOptions` in mkdocstrings-python (align the options schema with `parse_sphinx`'s actual signature), or\n2. Filter forwarded kwargs per parser signature before assigning `parser_options`, or\n3. 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.\n\nThank you.","author":{"url":"https://github.com/selbs","@type":"Person","name":"selbs"},"datePublished":"2026-08-07T15:17:41Z","url":"https://github.com/mkdocstrings/python/issues/337"}