14

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
ndou
  • 1,048
  • 10
  • 15
  • 3
    I don't see why this was closed. This seems to be a perfectly valid question capable of a fairly objective response. – James Mchugh Jun 03 '21 at 20:48

1 Answers1

14

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

enter image description here

numpydoc

enter image description here

ryanjdillon
  • 17,658
  • 9
  • 85
  • 110