[Tutor] Questions about the formatting of docstrings

Albert-Jan Roskam sjeik_appie at hotmail.com
Sat Jul 28 09:47:29 EDT 2018

On 27 Jul 2018 06:34, boB Stepp <robertvstepp at gmail.com> wrote:

I am near the end of reading "Documenting Python Code:  A Complete
Guide" by James Mertz, found at
https://realpython.com/documenting-python-code/  This has led me to a
few questions:

(1) The author claims that reStructuredText is the official Python
documentation standard.  Is this true?  If yes, is this something I
should be doing for my own projects?

(2) How would type hints work with this reStructuredText formatting?
In part of the author's reStructuredText example he has:

:param file_loc:  The file location of the spreadsheet
:type file_loc:  str

Hi Bob,

Have a look at numpydoc, which works with Sphinx. Numpydoc makes it much easier to read and write docstrings, while they can still be converted into nice looking docs, e.g html. See: https://codeandchaos.wordpress.com/2012/08/09/sphinx-and-numpydoc/


More information about the Tutor mailing list