Python and sphinx: bullet point list in multiline google style docstring

Question

I am currently documenting my Python project using Sphinx. I have come across an issue when including a bullet point list in the multi-line part of a docstring.

I would like to include a bulleted list, but one of the items is quite long. I would like to:

• have the bullet list correctly rendered through Sphinx
• but also have my code respecting PEP8 about line length (<79)

What would you advice for me to do for this docstring:

class geography():
""" Class defining a geography (cities and distance matrix)

This class implements a geography with a list of named cities with their
associated coordinates in a plane. Helper functions enable to :

- give a visual representation of that geography
- give a visual representation of the distance matrix
- give a visual representation of a configuration, a configuration being the repartition of some or all cities in pools

...

Last line is way over 79 characters.

Comments are then rendered through Sphinx. Adding a carriage return just breaks the bullet point list in Sphinx.

Eileen

Answer 1

You can break the bulleted line as you like. Just line up the continuation with the previous lines text like:

- give a visual representation of that geography
- give a visual representation of the distance matrix
- give a visual representation of a configuration, a configuration being the
  repartition of some or all cities in pools

Trunk

Thanks for your answer Stephen, I will try that as soon as I get 5 minutes to do so and keep you informed. Regards, Pierre – Sielen

Wonderful! This worked like a charm, my doc is still nicely built and I now comply to PEP 8. I will add an additional comment for non bulleted lists as I managed to apply a similar solution. – Sielen

If there is text before the list, I found I needed to leave a blank line before the list. Then the renderer can tell the list is not a continuation of that text. (Also shown in the example given in the original question.) – Peggi

Answer 2

Solution from @Stephen Rauch was the perfect one. I just wanted to add that it also works for non bulleted lists. I had a similar issue with comments for arguments of functions or methods. For example:

def permute_array(arr, seq):
""" Function to "square permute" a 2D array

This function's purpose is to enable distance matrices permutations. That 
is, for example, permute both lines and columns of the array so as to 
reorder a distance matrix.

Args:
    arr (numpy array): the array to permute. It should be square of size n.
    seq (iterable of int): a permutation of range(n) (should be of length n and contain every integer from 0 to n-1)

Last line is way too long.

However, a "same indentation level" line break just breaks the nice sphinx method documentation:

    Args:
        arr (numpy array): the array to permute. It should be square of size n.
        seq (iterable of int): a permutation of range(n) (should be of length n
        and contain every integer from 0 to n-1)

Badly built documentation

But, breaking the line with an identation just works fine.

    Args:
        arr (numpy array): the array to permute. It should be square of size n.
        seq (iterable of int): a permutation of range(n) (should be of length n
            and contain every integer from 0 to n-1)

Nicely built documentation

Eileen