I encourage you to take a look at numpydoc https://github.com/numpy/numpydoc (actual docs: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) which makes docstrings human+machine readable in a nice-ish manner. Just FYI.