Extra blank lines in a Sphinx unordered list

Question

I am writing documentation for my project using Sphinx and have found a difference in how two similar reStructuredText segements, given below, are rendered.

Example 1

Some text:

*  Item 0
*  Item 1
*  Item 2

   ::

       Some code
       Some code
       Some code
       Some code

   .. WARNING::
      Some text.

*  Item 3

Example 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

Example 1 is producing additional whitespace between list items Item 0, Item 1 and Item 2, but the second example renders without this additional spacing. See the final markup of example 1 and example 2. This only happens with the "basic" theme.

Why do I have to follow my second example then if I don't want the additional spacing produced by example 1?

Answer 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.