4 ms·

I've always been curious about docstring style. I've usually gone with numpy-style docstrings: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rs

by entee 11y ago

I've always been curious about docstring style. I've usually gone with numpy-style docstrings: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMEN... They tend to be easier to read than reST, and happen to be used by the packages I use most (numpy, scipy). They are also easily worked into sphynx/napoleon. 2 questions: 1.) Why use reST instead? 2.) Why isn't there a python-wide standard or best practices as is found for Scala/Java/others?

wcarss 11y ago
From [1], the "Docstring Standard" section of your link, "Our docstring standard uses re-structured text (reST) syntax". It seems like they use reST? 1 - https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMEN...
- yeukhon 11y ago
  That's referring to the syntax in the docstring format they developed is only supported by reST, render by Sphinx's integration with reST. For exmaple, .. image:: filename You don't get that in Markdown.
Spiritus 11y ago
I use Sphinx style because it gives me better auto-completion via Jedi[1][2]. Otherwise I really like the look of Google style docstrings[3]. There's some ongoing work[4][5] to get support for that in Jedi as well. [1] https://github.com/davidhalter/jedi https://github.com/davidhalter/jedi [2] https://github.com/davidhalter/jedi-vim https://github.com/davidhalter/jedi-vim [3] http://sphinxcontrib-napoleon.readthedocs.org http://sphinxcontrib-napoleon.readthedocs.org [4] https://github.com/davidhalter/jedi/issues/504 https://github.com/davidhalter/jedi/issues/504 [5] https://github.com/davidhalter/jedi/pull/617 https://github.com/davidhalter/jedi/pull/617