Python и sphinx: список маркеров в многострочной строке в стиле Google

Question

Я сейчас документирую свой проект на Python, используя Sphinx.Я столкнулся с проблемой при включении списка маркеров в многострочную часть строки документации.

Я хотел бы включить маркированный список, но один из пунктов довольно длинный.Я хотел бы:

• правильно отобразить список маркеров через Sphinx
• , а также иметь мой код с учетом PEP8 относительно длины строки (<79) </li>

Что бы вы посоветовали мне сделать для этой строки документации:

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

...

Последняя строка длиной более 79 символов.

Комментарии затем обрабатываются через Sphinx.Добавление возврата каретки просто нарушает список точек маркера в Сфинксе.

Answer 1

Решение от @ Стивена Рауха было идеальным.Я просто хотел добавить, что это также работает для не маркированных списков.У меня была похожая проблема с комментариями для аргументов функций или методов.Например:

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)

Последняя строка слишком длинная.

Однако разрыв строки "с тем же уровнем отступа" просто нарушает документацию по методу sphinx:

    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)

Плохо построенная документация

Но разрыв строки с помощью отступа просто отлично работает.

    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)

Прекрасно составленная документация

Answer 2

Вы можете разбить маркированную строку , как вам нравится.Просто выровняйте продолжение с текстом предыдущих строк, например:

- 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