Use exclusively napoleon extension for Sphinx to parse NumPy style docstrings
Currently,numpydoc
and napoleon
are both used as extensions to Sphinx.
These two extensions serve the same function: parsing in-code docstrings written in NumPy style (as opposed to the standard restructuredtext style) to put into the API reference section of the documentation.
We decided a while back to write the docstrings in NumPy style (see Issue #46).
While the documentation can be built alright (meaning there's no hard clash between the extensions) mixing this up makes it difficult to track which features of each extension are at work.
The effects of certain options on the rendered output tend to behave unexpectedly.
I suggest to remove numpydoc
from the list of extension used by the Minterpy documentation.
It appears napoleon
provides a better support for type hinting. Using solely numpydoc
creates the problem with linking mentioned in Issue #46.
Furthermore, the choice seems the safest as napoleon
is an official extension of Sphinx and therefore does not introduce an additional dependency in building the code.
One minor caveat: numpydoc
provides a shortcut to create a summary of attributes and methods of a class by simply listing them (just the identifiers) in the docstrings. The extension will parse the attributes and methods listed and create a two-column summary table (the first column is the name the second is the description taken from the docstrings of each properties/methods); I originally plan to show such tables for the Minterpy docs. But napoleon
does not provide this out of the box.
However, I manage to have a solution regarding the summary table using a Sphinx extension autosummary
which is also built-in.
So I think we can go ahead with this.
This issue is another step to resolve Issue #46.