wfdb-python
wfdb-python copied to clipboard
Improve examples in docstrings
Pull request #433 brings to mind some things that could be improved in docstrings more generally. Cleaning these up might be a good starter issue.
-
Obviously, code examples should be correct and actually work. :)
-
Code examples should also be self-contained if possible, and avoid referring to files in
sample-data
(most people reading the documentation are probably not running the code directly from the git repository.) In most cases, it's better to use examples from published databases on PhysioNet. -
Code examples should be written in a consistent style. We generally use numpy style (https://numpydoc.readthedocs.io/en/latest/format.html) for docstrings, but we haven't been entirely consistent. In particular, numpy style requires examples to be written in "doctest" style, like this:
"""
Examples
--------
>>> np.add([[1, 2], [3, 4]],
... [[5, 6], [7, 8]])
array([[ 6, 8],
[10, 12]])
"""
This format has some nice properties (it can be tested automatically by doctest, and formatted nicely by sphinx.) On the other hand, the "..." is a little annoying when you want to copy and paste an example.