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

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

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

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

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

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. Добавление возврата каретки просто нарушает список точек маркера в Сфинксе.

Источник

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
Источник

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

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)

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

Источник
Другие вопросы по тегам