sphinx-doc / sphinx-doc/sphinx
Napoleon docstring validation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Premises:
- I am opening the issue here as
napoleonis packaged with Sphinx - I checked both discussions and StackOverflow, but I didn't really get an up-to-date definitive answer
Is your feature request related to a problem? Please describe.
Normally I use numpydoc for my docstring style.
I recently started using its validation tool and it works mostly fine.
The problem is that some of my Python3 modules come with type-annotated functions and numpdoc doesn't yet support this.
For example functions like,
do_bla(
self, xxx: Iterable[Union[int, str, MyClass]]
) -> Tuple[int]:
"""
Parameters
----------
xxx: List[Union[int, str, MyClass]]
Description of xxx.
Returns
--------
bla: List[int]
List of blas.
"""
fails because it reads each annotation part as a different parameter.
So I decided to give a try to napoleon which instead seems to support them.
I couldn't find a validation tool for Napoleon - is there one?
Describe the solution you'd like
Essentially what numpydoc has, without requiring third-party solutions
Describe alternatives you've considered
There is darglint, but unfortunately seems to be discontinued and some linters like pylint do not seem to check for everything.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing Napoleon's existing docstring parsing behavior and comparing it with numpydoc's built-in validation checks, especially for annotated Python functions. Define the validation scope and acceptance criteria for parameter and return sections before identifying the relevant implementation and tests; done means validation works without a third-party tool.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100