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,但第二示例呈现没有这个额外的间距.请参见示例1和示例2的最终标记.这只发生在"基本"主题上.

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

Answer 1

从您的评论来看，问题似乎在于http://rst.ninjs.org上 reStructuredText 的渲染以及它在某个特定 CSS 主题下的外观。这对于 reStructuredText 来说并不是真正的问题。

\n\n

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

\n\n

我们可以通过研究项目符号列表的 reStructuredText 规范（重点是我的）来了解原因，

\n\n

\n

以“*”、“+”、“-”、“\xe2\x80\xa2”、“\xe2\x80\xa3”或“\xe2\x81\x83”开头，后跟空格的文本块，是项目符号列表项（也称为“无序”列表项）。列表项主体必须左对齐并相对于项目符号缩进；紧接着项目符号之后的文本决定缩进。

\n

\n\n

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

\n\n

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

\n