Repository navigation
Consider using sphinx.ext.napoleon instead of numpydoc #5
Description
As originally mentioned in astropy/astropy-helpers#270, we should explore whether to switch from numpydoc to sphinx.ext.napoleon. The main benefit would be to reduce the number of dependencies (we could remove numpydoc).
Packages can easily try out sphinx.ext.napoleon if they are using sphinx-astropy as they just need to do something like the following in their conf.py:
extensions.remove('numpydoc')
extensions.append('sphinx.ext.napoleon')
and presumably add a bunch of configuration for sphinx.ext.napoleon. If anyone fancies trying to do something like this with astropy core for example, feel free to.
If we decide to do this in the default config here, we should determine whether it will have a big impact on downstream packages, and if so we may have to make a new version of conf.py (v2).
Activity
pllim commentedon Nov 24, 2018
💯
eteq commentedon Nov 24, 2018
As I note for the record, I tested this once maybe ~15 months ago and there were a ton of what looked like fiddly-detail errors that scared me away from looking into it further.
That said, things may have improved since then. And I'm definitely a fan of the idea for all the reasons @astrofrog gave here.
nstarman commentedon Jun 21, 2021
Astropy main now uses numpydoc for cross references, and when numpydoc 1.20 is out, for numpy-style docstring validation. Also numpydoc is maintained as a part of numpy, so if we have numpy as a dependency it's not much to also keep numpydoc.
I like sphinx-Napoleon a lot — it has a slightly more flexible standard for docstrings that makes concision easier — but it doesn't seem worth the trouble to switch given the close ties between numpy and numpydoc.
Just my 2¢.
bsipocz commentedon Jun 21, 2021
This issue has been moved around for 6 years without making the switch. In the meantime, we stopped bundling numpydoc and it really got mainstream in the scientific python packages.
So my suggestion would be also to close this issue without spending any more cycles on refreshing the thinking about napoleon.
pllim commentedon Jun 21, 2021
Sure. I agree that we'll never get to it within cosmic timescale.