4

I documented some modules of a Python package I wrote using NumPy style, and I set up a readthedocs website to host the automatically generated documentation (with sphinx.ext.napoleon). Despite trying to follow the NumPy documentation style guidelines, the rendered docstrings don't appear to have the same appearance as NumPy's own documentation, which looks clearer to me. (I'm not talking about the overall html theme, but how the parameters and class methods are displayed)

My conf.py file and all .rsts of the documentation can be found in the repo. I also use nbsphinx and nbsphinx-link to render a Python Jupyter notebook, but I hope this doesn't interfere with napoleon/autodoc. I think that using numpydoc instead of sphinx.ext.napoleon isn't an option because of using nbsphinx. Also, if I'm not mistaken, using napoleon should be equivalent to using numpydoc.

How NumPy's documentation shows the parameters of a class:

numpy.array class docstrings showing the Parameters list

How my docs shows the parameters of a class, even though I wrote the docstrings following NumPy's docs style and use sphinx.ext.napoleon with napoleon_google_docstring = False in conf.py. (Notice the dotted list, how the description of the parameter is following the name and default values in the same line...)

AlloViz.Protein class docstrings showing the Parameters list

Francho Nerín Fonz
  • 311
  • 2
  • 7
  • 1
    ReadTheDocs is nice but I often ask myself why everyone want to use it? Why not generate your HTML output yourself and put it into the repo. Then you can use the "pages" feature of GitHub, GitLab or Gitea (e.g. on Codeberg) to make the HTML in your repo accessibale as a website. See (my [`buhtzology`](https://codeberg.org/buhtz/buhtzology#user-content-documentation) as an example. – buhtz Aug 02 '22 at 12:50
  • 1
    The NumPy documentation uses a different theme (pydata_sphinx_theme). – mzjn Aug 02 '22 at 12:50
  • @mzjn Thanks for your input. I tried with that theme, but the parameters and methods of the code docstrings are still not displayed as in NumPy's documentation. My issue is not with the overall html theme – Francho Nerín Fonz Aug 02 '22 at 13:01
  • So what is your issue then? Please be more specific. – mzjn Aug 02 '22 at 13:01
  • 1
    @mzjn I just added a couple of pictures! – Francho Nerín Fonz Aug 02 '22 at 14:25
  • 1
    "I think that using numpydoc instead of sphinx.ext.napoleon isn't an option". OK, but can't that be a problem? The NumPy documentation uses numpydoc. – mzjn Aug 02 '22 at 14:54
  • @mzjn You're right, I tried switching back to numpydoc and so far docs are building and nbsphinx is working alongside it without problems. At least with local sphinx-build, now it's time to wrestle with readthedocs. Thanks! – Francho Nerín Fonz Aug 02 '22 at 15:42
  • `Why not generate your HTML output yourself and put it into the repo. ` Because extracting and massaging API data is 80% of the job. – Mikko Ohtamaa Aug 03 '22 at 07:55

0 Answers0