Sphinx RTD主题和新行

Question

我已经用python3编写了一个库，现在正在记录这个类、它的方法、常量等。

对于列表或字典形式的常量，我遇到了一个微妙的格式问题。我的组织已经采取的立场是，为了可读性，列表和字典应该以以下格式编写……

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

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

在我的类中，有一些常量是列表，例如：

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

我已经将这个列表和所有其他类常量复制到了类docstring中，并写了一个段落来解释每个常量的意义。如果我想让html文档具有这种良好的格式，我可以使用竖线("|")来强制换行。

这是我的restructuredText：

|     **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

我打完了我的问题，然后不得不尝试一些有效的东西。我希望这个解决方案能帮助其他人。我的回答是混乱的，但很有效。如果有人有更好的解决方案，请把它贴出来！

显然，问题出在我对常量的声明和对其用法的解释之间的空行。删除空行。

但这会导致描述的第一行与描述的第一行运行在同一行上。要解决此问题，请在描述的第一行添加竖线。

但是THEEEEEENNNNN...这导致常量和它后面的常量之间几乎没有空格，这也很恼人。因此，我不得不通过在描述后的行上添加另一个竖线来强制新行。这是最终的解决方案：

|     **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遵从性时，使用Diffing是痛苦的。对于叙述性文档来说，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格式的超文本标记语言。

​

​