Use numpydoc to render documentation

[SnoopJ]

Closes #471

This changeset adds numpydoc to the documentation build requirements, better distinguishing between parameters and return values.

Typical function documentation before this changeset:

After this changeset:

Note that this does produce some Sphinx errors and warnings when building the documentation, generally because wfdb is not following numpydoc style exactly. Most of them look like small tweaks, many of them can probably be resolved by removing unnecessary indentation or introducing a literal code block. I'll leave that to the maintainers.

click for build log

``` Running Sphinx v4.5.0 making output directory... done [autosummary] generating autosummary for: changes.rst, convert.rst, index.rst, installation.rst, io.rst, plot.rst, processing.rst, wfdb-specifications.rst, wfdb.rst building [mo]: targets for 0 po files that are out of date building [html]: targets for 9 source files that are out of date updating environment: [new config] 9 added, 0 changed, 0 removed reading sources... [ 11%] changes reading sources... [ 22%] convert reading sources... [ 33%] index reading sources... [ 44%] installation reading sources... [ 55%] io reading sources... [ 66%] plot reading sources... [ 77%] processing reading sources... [ 88%] wfdb reading sources... [100%] wfdb-specifications /tmp/wfdb-python/venv/lib/python3.8/site-packages/numpydoc/docscrape.py:460: UserWarning: Unknown section Examples: in the docstring of adc in /tmp/wfdb-python/wfdb/io/_signal.py. warn(msg) /tmp/wfdb-python/venv/lib/python3.8/site-packages/numpydoc/docscrape.py:460: UserWarning: Unknown section Examples: in the docstring of adc in /tmp/wfdb-python/wfdb/io/_signal.py. warn(msg) /tmp/wfdb-python/venv/lib/python3.8/site-packages/numpydoc/docscrape.py:460: UserWarning: potentially wrong underline length... Parameters ------- in Main comparison function. Note: Make sure to be able to handle these ref/test scenarios:... in the docstring of compare in /tmp/wfdb-python/wfdb/processing/evaluate.py. warn(msg) /tmp/wfdb-python/venv/lib/python3.8/site-packages/numpydoc/docscrape.py:460: UserWarning: Unknown section Example in the docstring of compare in /tmp/wfdb-python/wfdb/processing/evaluate.py. warn(msg) /tmp/wfdb-python/venv/lib/python3.8/site-packages/numpydoc/docscrape.py:460: UserWarning: Unknown section Examples: in the docstring of adc in /tmp/wfdb-python/wfdb/io/_signal.py. warn(msg) /tmp/wfdb-python/venv/lib/python3.8/site-packages/numpydoc/docscrape.py:460: UserWarning: Unknown section Examples: in the docstring of adc in /tmp/wfdb-python/wfdb/io/_signal.py. warn(msg) /tmp/wfdb-python/wfdb/io/convert/csv.py:docstring of wfdb.io.convert.csv.csv_to_wfdb:273: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/csv.py:docstring of wfdb.io.convert.csv.csv_to_wfdb:279: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.rdedfann:5: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.rdedfann:10: WARNING: Definition list ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.rdedfann:12: WARNING: Definition list ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.rdedfann:13: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.read_edf:102: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.read_edf:103: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.wfdb_to_edf:91: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/edf.py:docstring of wfdb.io.convert.edf.wfdb_to_edf:92: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/matlab.py:docstring of wfdb.io.convert.matlab.wfdb_to_mat:81: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/matlab.py:docstring of wfdb.io.convert.matlab.wfdb_to_mat:82: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/wav.py:docstring of wfdb.io.convert.wav.read_wav:59: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/convert/wav.py:docstring of wfdb.io.convert.wav.read_wav:62: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/convert/wav.py:docstring of wfdb.io.convert.wav.read_wav:65: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/__init__.py:docstring of wfdb.io.record.rdsamp:54: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.adc'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.dac'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.get_absolute_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.get_elapsed_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.get_frame_number'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.to_dataframe'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.io.Record.wrsamp'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.io.MultiRecord.contained_combined_ranges'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.io.MultiRecord.contained_ranges'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.io.MultiRecord.get_absolute_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.io.MultiRecord.get_elapsed_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.io.MultiRecord.get_frame_number'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.io.MultiRecord.multi_to_single'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/docs/io.rst:24: WARNING: Title underline too short. WFDB Annotations --------------- /tmp/wfdb-python/docs/io.rst:24: WARNING: Title underline too short. WFDB Annotations --------------- /tmp/wfdb-python/wfdb/io/__init__.py:docstring of wfdb.io:1: WARNING: duplicate object description of wfdb.io, other instance in io, use :noindex: for one of them /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:62: WARNING: Definition list ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:80: WARNING: Definition list ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:152: WARNING: autosummary: stub file not found 'wfdb.io.Annotation.wrann'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/__init__.py:docstring of wfdb.io:1: WARNING: duplicate object description of wfdb.io, other instance in io, use :noindex: for one of them /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing:1: WARNING: duplicate object description of wfdb.processing, other instance in processing, use :noindex: for one of them /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing:1: WARNING: duplicate object description of wfdb.processing, other instance in processing, use :noindex: for one of them /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing:1: WARNING: duplicate object description of wfdb.processing, other instance in processing, use :noindex: for one of them /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing:1: WARNING: duplicate object description of wfdb.processing, other instance in processing, use :noindex: for one of them /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing.qrs.gqrs_detect:110: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing.qrs.gqrs_detect:112: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing.qrs.gqrs_detect:115: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing.qrs.gqrs_detect:117: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing.qrs.gqrs_detect:122: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/processing/__init__.py:docstring of wfdb.processing:1: WARNING: duplicate object description of wfdb.processing, other instance in processing, use :noindex: for one of them /tmp/wfdb-python/wfdb/processing/evaluate.py:docstring of wfdb.processing.evaluate.Comparitor.compare:6: WARNING: Title underline too short. Parameters ------- /tmp/wfdb-python/wfdb/processing/evaluate.py:docstring of wfdb.processing.evaluate.Comparitor.compare:6: CRITICAL: Unexpected section title. Parameters ------- /tmp/wfdb-python/wfdb/__init__.py:docstring of wfdb.io.record.rdsamp:54: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:1: WARNING: duplicate object description of wfdb.io.record.Record, other instance in io, use :noindex: for one of them /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.adc'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.dac'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.get_absolute_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.get_elapsed_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.get_frame_number'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.to_dataframe'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.Record:141: WARNING: autosummary: stub file not found 'wfdb.Record.wrsamp'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:1: WARNING: duplicate object description of wfdb.io.record.MultiRecord, other instance in io, use :noindex: for one of them /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.MultiRecord.contained_combined_ranges'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.MultiRecord.contained_ranges'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.MultiRecord.get_absolute_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.MultiRecord.get_elapsed_time'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.MultiRecord.get_frame_number'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.MultiRecord:103: WARNING: autosummary: stub file not found 'wfdb.MultiRecord.multi_to_single'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_absolute_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_elapsed_time:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:6: ERROR: Unexpected indentation. /tmp/wfdb-python/wfdb/io/record.py:docstring of wfdb.io.record.BaseRecord.get_frame_number:7: WARNING: Block quote ends without a blank line; unexpected unindent. /tmp/wfdb-python/docs/wfdb.rst:24: WARNING: Title underline too short. WFDB Annotations --------------- /tmp/wfdb-python/docs/wfdb.rst:24: WARNING: Title underline too short. WFDB Annotations --------------- /tmp/wfdb-python/wfdb/__init__.py:docstring of wfdb:1: WARNING: duplicate object description of wfdb, other instance in wfdb, use :noindex: for one of them /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:1: WARNING: duplicate object description of wfdb.io.annotation.Annotation, other instance in io, use :noindex: for one of them /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:62: WARNING: Definition list ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:80: WARNING: Definition list ends without a blank line; unexpected unindent. /tmp/wfdb-python/wfdb/io/annotation.py:docstring of wfdb.io.annotation.Annotation:152: WARNING: autosummary: stub file not found 'wfdb.Annotation.wrann'. Check your autosummary_generate setting. /tmp/wfdb-python/wfdb/__init__.py:docstring of wfdb:1: WARNING: duplicate object description of wfdb, other instance in wfdb, use :noindex: for one of them /tmp/wfdb-python/wfdb/__init__.py:docstring of wfdb:1: WARNING: duplicate object description of wfdb, other instance in wfdb, use :noindex: for one of them looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [ 11%] changes writing output... [ 22%] convert writing output... [ 33%] index writing output... [ 44%] installation writing output... [ 55%] io writing output... [ 66%] plot writing output... [ 77%] processing writing output... [ 88%] wfdb writing output... [100%] wfdb-specifications generating indices... genindex py-modindex done writing additional pages... search done copying static files... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded, 97 warnings. The HTML pages are in _build/html. ```

[bemoody]

Excellent, thank you!