16

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?

0

1 Answer 1

15

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

2
  • What sphinx-theme was used for this?
    – bad_coder
    Commented Apr 6, 2020 at 22:31
  • 1
    @bad_coder I think it was Alabaster. Commented Apr 7, 2020 at 8:11

Not the answer you're looking for? Browse other questions tagged or ask your own question.