I think for the current docstring standard there needs to be a one-line summary at the top. If you need to elaborate after that, then you can give a blank line. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#id6