Menu
I am writing documentation for a Python project using Numpy-style docstrings.
numpydoc and napoleon are two Sphinx extensions that parse Numpy-style docstrings to generate documentation. The first one is used for the Numpy project itself, the second is shipped with Sphinx.
What are the pros and cons of using one extension over the other?
318
Napoleon is a extension that enables Sphinx to parse both NumPy and Google style docstrings - the style recommended by Khan Academy. Napoleon is a pre-processor that parses NumPy and Google style docstrings and converts them to reStructuredText before Sphinx attempts to parse them.
A documentation string (docstring) is a string that describes a module, function, class, or method definition. The docstring is a special attribute of the object ( object. __doc__ ) and, for consistency, is surrounded by triple double quotes, i.e.: """This is the form of a docstring.
The resulting format of each a bit different, and the default behavior of napoleon links to known datatypes in the python documentation, and it is slightly more condensed (numpydoc displays a bit like how it appears in the docstring). Below are examples of each, both using the default sphinx theme.
An issue in astropy's issue tracker that states napolean is a hard dependency for IPython, and they have since migrated from numpydoc to napolean.
They mention it has stricter syntax requirements, but I haven't tested either too much to comment on that.
napoleon
numpydoc
168
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
