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（强调我的），

中看出原因

  

以“*”，“+”，“ - ”，“•”，“‣”或“⁃”开头的文本块，后跟空格，是一个项目符号列表项（又名“无序”列表项目）。列表项主体必须左对齐并相对于项目符号缩进;子弹确定缩进后的文本。

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

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