Python 和 sphinx：多行 google 样式文档字符串中的项目符号列表答案

【问题标题】：Python and sphinx: bullet point list in multiline google style docstringPython 和 sphinx：多行 google 样式文档字符串中的项目符号列表
【发布时间】：2019-02-13 19:16:40
【问题描述】：

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

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

通过 Sphinx 正确呈现项目符号列表
但也有我的代码尊重 PEP8 关于行长 (

你会建议我为这个文档字符串做什么：

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 中的项目符号列表。

【问题讨论】：

标签： python python-sphinx docstring google-style-guide

【解决方案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

【讨论】：

感谢斯蒂芬的回答，我会在有 5 分钟的时间尝试这样做并随时通知您。问候，皮埃尔
太棒了！这就像一个魅力，我的文档仍然构建得很好，我现在遵守 PEP 8。当我设法应用类似的解决方案时，我将为非项目符号列表添加额外的评论。

【解决方案2】：

@Stephen Rauch 的解决方案是完美的。我只是想补充一点，它也适用于非项目符号列表。对于函数或方法的参数，我对 cmets 有类似的问题。例如：

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

【讨论】：