Napoleon docstring validation

[HealthyPear]

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.

[electric-coder]

I couldn't find a validation tool for Napoleon - is there one?

No there isn't one. You can use pylint's Docstyle checker but it has very limited features.

Sphinx itself isn't able to correctly process every type that can be included in a docstring or a signature and that's just to build the documentation not to also validate correctness between dynamic types and static docstrings.

Describe the solution you'd like Essentially what numpydoc has, without requiring third-party solutions

I don't think this is even on the event horizon. After years of using Sphinx the buglist just seems to keep growing, likely because the typing module doesn't stop changing and half of it is deprecated after a shortwhile anyway. So building in extra features when there are unresolved core features that affect the entire stack built on Sphinx doesn't seem the right way to go.