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 <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.
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.l..., `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
On 12 Sep 2019, at 5:50 am, Egor Panfilov <egor.v.panfilov@gmail.com> wrote: 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.
The review workflow is “good enough” for sure, and we’ve been doing all right with that from the very beginning of the project (together with building the docs with Travis). However, one use case for *perfect* docstrings is that we can potentially extract type annotation information automatically if all of our docstrings conform to the correct standard. That is potentially extremely valuable.
On July 16, 2019 06:42:03 Juan Nunez-Iglesias <jni@fastmail.com> wrote:
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.
It wasn't clear to me whether Gaël was saying that they're using Napoleon or not. I don't have a good sense of its features compared to numpydoc. Doing documentation checking would be great, though. Best regards, Stéfan
participants (3)
-
Egor Panfilov -
Juan Nunez-Iglesias -
Stefan van der Walt