Question

我在python 3中编写了一个库，现在正在记录类，它的方法，常量等。

我对列表或dicts的常量有一个微妙的格式问题。为了便于阅读，我的组织采取了以下格式编写列表和词组的立场......

my_list = [
    'One',
    'Two',
    'Three',
]

my_dict = {
    'One': 1,
    'Two': 2,
    'Three': 3,
}

在我的班级中，我有一些常量列表，例如：

STD_LIST = [
    'item1',
    'item2',
    'item3',
]

我已将此列表和所有其他类常量复制到类docstring中，并编写了一段解释每个重要性的段落。如果我希望html文档具有这种漂亮的格式，我使用垂直条（“|”）来强制换行。

这是我的重组文本：

|     **STD_LIST = [**
|         **'item1',**
|         **'item2',**
|         **'item3',**
|     **]**

        This list is very important. Please do not modify it unless you know
        what you are doing. Best not to touch it ever!

        .. warning:: Don't touch :py:const:`STD_LIST` unless you know what \
        you are doing.

但接下来会发生以下情况：

这里的问题是，就像我说的那样微妙，但我是一个完美主义者。记录正常常量时，描述将缩进。当使用垂直条时，它会破坏这种压痕。（与下图比较）

我发现如果我删除常量声明和描述之间的空白行，这会使描述继续在列表的最后一行。如果我然后在描述的第一行添加一个垂直条，它会完全纠正这个问题，但是由于不在它们之间添加空行而导致下一个常数向下发生问题。

在这种情况下，有谁知道如何与reST和Sphinx实现一致性？我认为能够强制在这个文档字符串中的常量之间换行也是一个充分的解决方法。

Answer 1

我完成了输入我的问题，然后不得不尝试一些有效的方法。我希望这个解决方案有助于其他人。我的回答很混乱，但有效。如果有人有更好的解决方案，请发布！

显然问题是我的常量声明和我对其使用的解释之间的空白。删除空白行。

但是这导致描述的第一行与描述的第一行在同一行上运行。要解决此问题，请在说明的第一行添加一个垂直条。

但是他们......这导致了常数和它之后几乎没有空格，这也很烦人。所以我不得不通过在描述之后在线上添加另一个垂直条来强制换行。这是最终的解决方案：

|     **STD_LIST = [**
|         **'item1',**
|         **'item2',**
|         **'item3',**
|     **]**
|         This list is very important. Please do not modify it unless you know
          what you are doing. Best not to touch it ever!

          .. warning:: Don't touch :py:const:`STD_LIST` unless you know what \
          you are doing.
|

    **NEXT_CONST = 'Stackoverflow.com is amazing!'**
        A shoutout to the stackoverflow.com admins and users. This is a normal constant 
        string and doesn't need any vertical bar trickery to get Sphinx to format it 
        nicely.

以下是格式良好的输出，正是我所寻找的：

例外：当描述以警告结束时，不需要在警告之后添加垂直条。相反，将垂直条移动到文本描述之后的行，然后在警告之前包括一个空行，如下所示：

|     **STD_LIST = [**
|         **'item1',**
|         **'item2',**
|         **'item3',**
|     **]**
|         This list is very important. Please do not modify it unless you know
          what you are doing. Best not to touch it ever!
|

          .. warning:: Don't touch :py:const:`STD_LIST` unless you know what \
          you are doing.

    **NEXT_CONST = 'Stackoverflow.com is amazing!'**
        A shoutout to the stackoverflow.com admins and users. This is a normal constant 
        string and doesn't need any vertical bar trickery to get Sphinx to format it 
        nicely.

Answer 2

我会使用code-block和其他标记。我不在叙述性文档的段落中使用换行符，因为它不是代码。当线长度改变并重新贴合到PEP8时，差异是很痛苦的。 PEP8完全不需要叙述文档;将您的PEP8保存在Python代码中，而不是reStructuredText源。

Some introductory text about ``STD_LIST``.

    .. code-block:: python

        STD_LIST = [
            'item1',
            'item2',
            'item3',
        ]

    This list is very important. Please do not modify it unless you know what you are doing. Best not to touch it ever!

    .. warning::

        Don't touch :py:const:`STD_LIST` unless you know what you are doing.

Some introductory text about ``NEXT_CONST``.

    .. code-block:: python

        NEXT_CONST = 'Stackoverflow.com is amazing!'

    A shoutout to the stackoverflow.com admins and users. This is a normal constant string and doesn't need any vertical bar trickery to get Sphinx to format it nicely.

这是招标的reStructuredText为HTML。

Sphinx RTD主题和新线

2 个答案: