Use Napoleon instead of Numpydoc ? #11440

Activity

1. lesteve commented on Jul 5, 2018

   

   lesteve

   on Jul 5, 2018

   Last edited by lesteve

   Member

   More actions

   Last time I tried (maybe 1-2 years ago), there were some errors when building the doc with napoleon and it was not immediately obvious how to fix them. Googling at the time, it was not immediately clear what the differences were between napoleon and numpy-doc. There may also be small differences in the doc output that are hard to spot given the size of the scikit-learn documentation.

   I would be in favour of waiting for 0.20 before merging a PR that switches to napoleon, so that quirks can be spotted in the dev doc until the 0.21 release.

   numpydoc has seen some fixes by @jnothman and @amueller semi-recently (maybe a few months ago) so maybe they have some informed opinion.
2. GaelVaroquaux commented on Jul 5, 2018

   

   GaelVaroquaux

   on Jul 5, 2018 via email

   Member

   More actions

   I would be in favour of waiting for 0.20 before merging a PR that switches to napoleon, so that quirks can be spotted in the dev doc until the next release.

   +1.
3. rth commented on Jul 5, 2018

   

   rth

   on Jul 5, 2018

   Member

   More actions

   I'm also not clear on the differences between the two feature-wise (their documentations are not too explicit about this point), I have used both in the past.

   However, another point to consider that is that numpydoc had extensive contributions by Joel (and other scikit-learn developers) while, unless I am mistaken no one contributed to sphinx.ext.napoleon too much.

   So this would mean replacing a working and well known dependency, by another one which potentially will require more maintenance work. The end result is that new contributors will not need to install numpydocs when they run tests or build docs locally, but is that worth the effort?
4. GaelVaroquaux commented on Jul 5, 2018

   

   GaelVaroquaux

   on Jul 5, 2018 via email

   Member

   More actions

   Is there a long-term reason that Napoleon would get less maintenance than numpydocs if projects switch to it? It's embedded in sphinx, so it will get a lot of exposure. Of course, it's a question of community dynamics, and there is a lot of social in there.
5. jnothman commented on Jul 5, 2018

   

   jnothman

   on Jul 5, 2018 via email

   Member

   More actions

   I have tried to maintain numpydoc, but I acknowledge that it's very hacky. We only recently adopted the numpydoc dependency rather than a vendored and tweaked version. After 0.20, it would be worth considering Napoleon, but we'll have to be careful to check for feature parity.
6. jorisvandenbossche commented on Jul 6, 2018

   

   jorisvandenbossche

   on Jul 6, 2018

   Member

   More actions

   What is the original reason to bring this up? Only that napoleon is included in sphinx? Or that we think it actually works better, or is better maintained?
7. GaelVaroquaux commented on Jul 6, 2018

   

   GaelVaroquaux

   on Jul 6, 2018 via email

   Member

   More actions

   Only that napoleon is included in sphinx?

   That it's included in sphinx. I tend to hope that it is more likely to become a community standard. Everybody who does sphinx docs has napoleon.
8. cmarmo

   added

   Documentation

   Needs Decision - CloseRequires decision for closingRequires decision for closing

   on Jan 17, 2022
9. cmarmo commented on Jan 17, 2022

   

   cmarmo

   on Jan 17, 2022

   Contributor

   More actions

   Based on how other project have managed similar issues (matplotlib#5743, astropy-sphinx#5) and the effort put in #21350, I believe this one can be closed.
10. GaelVaroquaux commented on Jan 17, 2022

    

    GaelVaroquaux

    on Jan 17, 2022

    Member

    More actions

    Sounds good with me. I'm closing it.
11. GaelVaroquaux

    closed this as completedon Jan 17, 2022