Skip to content

Fix Issue #109: Use napoleon to parse NumPy style docstrings

Damar Wicaksono requested to merge dev-109 into dev
  • Remove numpydoc from the list of Sphinx extension; the built-in extension napoleon is now exclusively used in the docs for parsing the docstrings written in NumPy style.
  • A custom directive has been added to create a summary table for public attributes, properties, and methods of classes. The implementation is based on the built-in autosummary extension.
  • The typehints in the functions/methods signatures are now hidden in the documentation to reduce cluttering.
  • All the relevant docstrings and the sections in the documentation has been updated to show a summary table. There is no functional change and no addition to the in-code documentation itself.

This MR should resolve Issue #109 (closed). The documentation will be built upon merging to the dev branch. But, please test the documentation build locally by first installing the dependencies via pip install -e .[docs].

A couple of additional remarks:

  • There is no functional changes to the codebase; only some docstrings have been altered so they can conform to the new Sphinx directive. So hopefully, pytest won't fail.
  • There is no update or fix to the documentation itself beyond the properties/methods summaries. Missing documentation, inconsistencies, and typos remain and it is not the aim of this MR to resolve them.

Therefore, please review only the following:

  • whether the documentation can be built locally using the dependencies prescribed in setup.cfg (automatically installed with pip install .[docs]), and
  • whether the look of the API reference section is in general okay and nothing is broken.

Once merged, we can continue the work on resolving Issue #46.

Edited by Damar Wicaksono

Merge request reports

Loading