Napoleon: Unify the type preprocessing logic

Previously, there were two type preprocessing functions:
`_convert_type_spec` (used in Google-style docstrings) and
`_convert_numpy_type_spec` (used in Numpy-style docstrings).

The Google version simply applied type-alias translations or wrapped
the text in a `:py:class:` role.

The Numpy version does the same, plus adds special handling for keywords
`optional` and `default` and delimiter words `or`, `of`, and `and`. This
allows one to write in natural language, like `Array of int` instead of
`Array[int]` or `Widget, optional` instead of `Optional[Widget]` or
`Widget | None`. Numpy style is described in full at:
https://numpydoc.readthedocs.io/en/latest/format.html#parameters

This commit eliminates the distinction and allows Google-style
docstrings to use these preprocessing rules.
This commit is contained in:
Chris Barrick
2024-11-19 20:33:19 -05:00
committed by Adam Turner
parent 0dbaa5b6d1
commit 8d75ae2d6b
2 changed files with 35 additions and 38 deletions

View File

@@ -17,7 +17,7 @@ from sphinx.ext.napoleon import Config
from sphinx.ext.napoleon.docstring import (
GoogleDocstring,
NumpyDocstring,
_convert_numpy_type_spec,
_convert_type_spec,
_recombine_set_tokens,
_token_type,
_tokenize_type_spec,
@@ -1332,7 +1332,7 @@ Do as you please
expected = """\
Do as you please
:Yields: :py:class:`str` -- Extended
:Yields: :class:`str` -- Extended
"""
assert str(actual) == expected
@@ -2677,7 +2677,7 @@ definition_after_normal_text : int
)
for spec, expected in zip(specs, converted, strict=True):
actual = _convert_numpy_type_spec(spec, translations=translations)
actual = _convert_type_spec(spec, translations=translations)
assert actual == expected
def test_parameter_types(self):