Hi Juan,

I personally feel that we should not add such scripts to the main repo, and rather wait for their inclusion into Sphinx/napoleon/etc.

I think the maintenance cost of such custom linter would be comparable or higher than the benefits of using it. One docstring example, a link to NumPy standard, and Sphinx translator in CI should be sufficient for everyone to write "good enough" docstrings.

For complex docstrings (e.g. with non-trivially indented ASCII art or multiple nesting (https://scikit-image.org/docs/dev/api/skimage.feature.html#skimage.feature.local_binary_pattern, `method`), I believe the person who submits a PR still needs to validate the change locally by building the docs. Having such cases covered by the custom linter would not be trivial.

Regards,

Egor

On Tue, 16 Jul 2019 at 16:41, Juan Nunez-Iglesias <jni@fastmail.com> wrote:

Hi all!

There is a thread on the NumPy mailing list discussing a linter that pandas uses for numpydoc docstrings. It sounds super useful and I think we should adopt it. =)

https://mail.python.org/pipermail/numpy-discussion/2019-July/079843.html

Gaël additionally proposes that this should be pushed to napoleon, a Sphinx now-built-in extension that supports the numpydoc standard. Perhaps we should move to napoleon also.

Waiting to hear your thoughts, will propose a PR if people are on board.

Juan.
_______________________________________________
scikit-image mailing list -- scikit-image@python.org
To unsubscribe send an email to scikit-image-leave@python.org