问题
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?
回答1:
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
来源：https://stackoverflow.com/questions/36715801/difference-between-sphinxcontrib-napoleon-and-numpy-numpydoc