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!