Sphinx gotchas

Here is a list of common gotchas when formatting Python docstrings for Sphinx and the Napoleon style.

Verbatim code blocks

Verbatim code blocks, e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented:

a nice example of python code follows::

    def foo(bar, baz):
        qux = bar + baz

        return qux

here we can restart text flow