Question

我目前正在使用Sphinx记录我的Python项目。在文档字符串的多行部分中包括项目符号列表时，我遇到了一个问题。

我想包括一个项目符号列表，但是其中一项很长。我想：

具有通过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渲染注释。添加回车符只会破坏Sphinx中的项目符号点列表。

Answer 1

您可以根据需要break the bulleted行。只需将延续与前面的文本对齐即可：

- 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

Answer 2

来自@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)

Badly built 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)

Nicely built documentation

Python和Sphinx：多行Google样式文档字符串中的项目符号点列表

2 个答案: