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.
More details
The Numpy-style preprocessing code lived between the GoogleDocstring and NumpyDocstring classes. This was kinda an awkward location when the code would become shared by both classes.
This PR is broken into two commits. The first moves the code to a more palatable location. The second migrates GoogleDocstring to use the previously-named _convert_numpy_type_spec.
I think it will be much easier to review the diffs individually rather than the diff for the whole PR.
Subject: Unify the type preprocessing logic in Napoleon
Feature or Bugfix
Purpose
Allow Google-style docstrings to use the
optionalanddefaultkeywords described at https://numpydoc.readthedocs.io/en/latest/format.html#parametersDetail
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
optionalanddefaultand delimiter wordsor,of, andand. This allows one to write in natural language, likeArray of intinstead ofArray[int]orWidget, optionalinstead ofOptional[Widget]orWidget | None. Numpy style is described in full at: https://numpydoc.readthedocs.io/en/latest/format.html#parametersThis commit eliminates the distinction and allows Google-style docstrings to use these preprocessing rules.
More details
The Numpy-style preprocessing code lived between the GoogleDocstring and NumpyDocstring classes. This was kinda an awkward location when the code would become shared by both classes.
This PR is broken into two commits. The first moves the code to a more palatable location. The second migrates GoogleDocstring to use the previously-named
_convert_numpy_type_spec.I think it will be much easier to review the diffs individually rather than the diff for the whole PR.