python-sphinx - 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

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

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

我们可以通过研究 reStructuredText specification on bullet lists 来了解原因。 (强调我的)，

A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item). List item bodies must be left-aligned and indented relative to the bullet; the text immediately after the bullet determines the indentation.

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

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