Unify the type preprocessing logic in Napoleon #13146
Conversation
cbarrick
force-pushed
the
napoleon-preprocess
branch
5 times, most recently
from
8856704 to
223a7cb
Compare
cbarrick
force-pushed
the
napoleon-preprocess
branch
from
223a7cb to
8f2a345
Compare
|
Friendly ping! Any concerns with this change? |
This puts all preprocessing code above both docstring classes, rather than in between. This is in preparation to making both docstring classes share the same preprocessing.
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.
cbarrick
force-pushed
the
napoleon-preprocess
branch
from
8f2a345 to
daacf40
Compare
|
@AA-Turner Can you take a look at this PR, or route it to the most appropriate reviewer? Am I missing anything from this change? Are there any concerns from the maintainers? I am periodically rebasing this onto master to ensure it remains mergable. I may be a tad unresponsive over the winter holidays. Happy to pick this back up in the new year. |
|
Hi Chris (@cbarrick), Thank you for keeping this up-to-date -- we squash-merge PRs in general so merging master might be easier than rebasing, to save some time. Likewise, thank you for the PR -- Napoleon is sadly a little neglected, so improvements here are greatly appreciated. You note that the change here would serve to expand the A |
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 separate 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.