Sphinx gotchas

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

Sphinx

Lists

All sorts of lists require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet

Bad:

this is a bad example that will not be interpreted as a list
preceding text
- foo
- bar
- baz
following text

Good:

this is some text preceding the list

- foo
- bar
- baz
- this is a rather long-ish paragraph inserted in the list
  with line continuation
- qux

this is some text following the list

Bad:

- foo
- nested lists also requires empty lines, but they are missing here
  - inner list 1
  - inner list 2
- outer list continues here

Good:

surrounding text

- foo
- nested lists also requires empty lines

  - inner list 1
  - inner list 2

- outer list continues here

surrounding text

Verbatim source code

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:

Bad:

This does not work as there is a single column and no empty line before code:
    def foo(bar, baz):
        qux = bar + baz

        return qux

Good:

a nice example of python code follows::

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

        return qux

here we can restart text flow

Inline code samples use double backquotes, and not single ones.

Bad:

you have to instantiate the method `def foo(bar): pass` in order to use this abstract class

Good:

you have to instantiate the method ``def foo(bar): pass`` in order to use this abstract class

Napoleon

Docstring sections

See the list of docstring sections supported by Napoleon. Everything else will not be typeset with a dedicated heading, you will have to do so explicitly using reStructuredText markup.

Args

Entries in Args section do not start with bullets, but just with argument names (as any other Napoleon section). Continuation lines should be indented.

Bad:

Args:
    - foo (int): first argument
    - bar: second argument
    - baz (bool): third argument

Good:

Args:
    foo (int): first argument
    bar: second argument, which happen to have a fairly
        long description of what it does
    baz (bool): third argument

Returns

In Returns section you need to use ":" carefully as, if present, it will be interpreted as a separator between return type and description. Also, the description of return value should not start on the same line of "Returns:", but on the subsequent one, indented.

Bad:

Returns:
    this does not work (colon will be interpreted as type/desc separator), a dict with keys:

    - foo
    - bar
<pre>

<u>Good:</u>
<pre>
Returns:
    this works (there is no colon) a dict with keys

    - foo
    - bar

Good:

Returns:
    dict: this works again (''first'' colon identifies the type) a dict with keys:

    - foo
    - bar

Bad:

Returns: this is not good either, you need to start a paragraph

See also

• Python style guide