7

我正在使用 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，但第二个示例呈现时没有这个额外的间距。请参阅示例 1和示例 2的最终标记。这只发生在“基本”主题中。Item 1Item 2

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

4

1 回答 1

1

From your comments it seems that the issue is with the rendering of reStructuredText on http://rst.ninjs.org and how this looks with one particular CSS theme. This is not really an issue with reStructuredText.

Ignoring the styling issues, the reason you are seeing two different behaviours between the two examples is because the two examples are different: in the first the code block is part of list item Item 2; in the second example the code block is not, and therefore closes the list above it and Item 3 therefore starts a new list.

We can see why from studying the reStructuredText specification on bullet lists (emphasis mine),

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.

In your first example the :: is aligned with the start of the text bullet list item, and so is part of the list item body. In the second example the :: is not at the same level of identation as the list item text and so closes the list and begins a code block (which is not a child of the list item). This is obvious if we compare the HTML produced by example 1 and example 2.

The take away point is that the start of the text in a list item defines the level of indentation which you must match if you want to add to the body of that list item.

于 2013-06-05T12:16:08.447 回答