Sphinx 无序列表中的额外空行

Question

我正在使用 Sphinx 为我的项目编写文档，并发现下面给出的两个相似的 reStructuredText 段的呈现方式有所不同。

示例 1

Some text:

*  Item 0
*  Item 1
*  Item 2

   ::

       Some code
       Some code
       Some code
       Some code

   .. WARNING::
      Some text.

*  Item 3

示例 2

Some inline text:

*  Item 0
*  Item 1
*  Item 2

  ::                           <-- One less space before the :: marker

       Some code
       Some code
       Some code
       Some code

  .. WARNING::                 <-- One less space before the .. marker
      Some warning text.

*  Item 3

示例 1 在列表项 Item 0、Item 1 和 Item 2 之间产生了额外的空白，但第二个示例呈现时没有这个额外的间距。查看example 1 和example 2 的最终标记。这只发生在“基本”主题中。

如果我不想要示例 1 产生的额外间距，为什么我必须遵循我的第二个示例？

Answer 1

从您的 cmets 看来，问题似乎在于http://rst.ninjs.org 上的 reStructuredText 的呈现以及它与一个特定的 CSS 主题的外观。这不是 reStructuredText 的真正问题。

忽略样式问题，您在两个示例之间看到两种不同行为的原因是因为这两个示例不同：第一个代码块是列表项Item 2 的一部分；在第二个示例中，代码块是 not，因此关闭了它上面的列表，Item 3 因此启动了一个新列表。

我们可以通过研究reStructuredText specification on bullet lists（重点是我的）来了解原因，

以“*”、“+”、“-”、“•”、“‣”或“⁃”开头，后跟空格的文本块是项目符号列表项（又名“无序列表”物品）。列表项正文必须左对齐并相对于项目符号缩进； 项目符号后面的文本决定缩进。

在您的第一个示例中，:: 与文本项目符号列表项的开头对齐，因此也是列表项正文的一部分。在第二个示例中，:: 与列表项文本不在同一标识级别，因此关闭列表并开始一个代码块（它不是列表项的子项）。如果我们比较 example 1 和 example 2 生成的 HTML，这一点很明显。

要点是列表项中文本的开头定义了如果要添加到该列表项的正文中必须匹配的缩进级别。