MIT-LCP / wfdb-python

Native Python WFDB package
MIT License
730 stars 298 forks source link

HTML documentation does not distinguish between parameters and return values #471

Closed SnoopJ closed 7 months ago

SnoopJ commented 7 months ago

NOTE: I am filing this issue on behalf of a user who asked about wfdb in the #python channel on the Libera.chat IRC network.

The wfdb HTML documentation does not distinguish between parameters and return values, with a fairly confusing presentation to the user who is not aware of this flaw:

Screenshot of wfdb documentation for `wfdb.processing.get_filter_gain()` showing the return values listed alongside parameters with no distinction between the two

It seems that although wfdb uses the numpydoc style of docstrings, these docstrings are not being properly processed by the project's Sphinx configuration.

This is happening because wfdb is not using the numpydoc Sphinx extension. Installing a compatible version (numpydoc<1.6 is required by wfdb's current Sphinx version) and adding it to the extension list in conf.py produces a much more legible rendering. See #472.