sphinx-doc / sphinx-doc/sphinx

Napoleon docstring validation

Open
#11,237 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:napoleon
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 napoleon is 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.