How to create a nested list in reStructuredText?

Question

I am trying to create a properly nested list using the following code (following Sphinx and docutils docs):

1. X

  a. U
  b. V
  c. W

2. Y
3. Z

I expect this to result in two OLs but I get the following output instead:

<ol class="arabic simple"> 
  <li>X</li> 
</ol> 

<blockquote> 
  <div>
    <ol class="loweralpha simple"> 
      <li>U</li> 
      <li>V</li> 
      <li>W</li> 
    </ol> 
  </div>
</blockquote> 

<ol class="arabic simple" start="2"> 
  <li>Y</li> 
  <li>Z</li> 
</ol> 

What am I doing wrong? Is it not possible to get the following result?

<ol class="arabic simple"> 
  <li>X
    <ol class="loweralpha simple"> 
      <li>U</li> 
      <li>V</li> 
      <li>W</li> 
    </ol> 
  </li>
  <li>Y</li> 
  <li>Z</li> 
</ol> 

Asyut

Answer 1

Make sure the nested list is indented to the same level as the text of the parent list (or three characters, whichever is greater), like this:

1. X

   a. U
   b. V
   c. W

2. Y
3. Z

Then you'll get the output you expected.

Severus

It appears that this is not exactly correct. In my case I was using * as the list indicator and when I indented my next line the two characters needed to line up with the text of the parent list, my list was treated as a separate list inside of a blockquote. The empirical rule I've found is that the inner list must be indented at least three characters. – Chemnitz

@Chemnitz Thanks! I updated the answer to include that caveat. – Severus

Indenting the inner list with 3 spaces didn’t work for me when using * lists. I think the answer was right the first time. – Draft

There is no "three character rule". The start column of the list item's content sets the required indentation for further content of this list item. If you move "X" to the next line, column 2, then the sub-list (a., b., c.) must start at column 2. – Laoag

Answer 2

If you want Sphinx to take care of the numbering for you, do this.

#. X
#. Y

   #. u 
   #. v 

#. Z

Cheat

Just re-highlighting this detail since it still applies: u and v must be indented at least 3 spaces (not 2 spaces), to match the text of the parent level. Otherwise, you'll get "1. Z" instead of "3. Z". – Heer

@S.Kirby It also seems that one must indent more, if one uses a list item like iii., which uses more places. It seems text has to be aligned and there seems not to be a specific count of spaces one can use for all cases. – Aq

Please note that the extra empty lines are also important here. So you will need 3 spaces for each element of the nested sub list, and above and below an empty line. – Kozak

The important point is the indentation of the preceding item text. This may be less than 3 if the text starts on the line following the list marker. – Laoag

Answer 3

If you don't want to change the indentation of the nested list, you can adjust the containing list item's indentation to match it. To get an indentation less than 3 spaces, start the item text on the line after the list marker (the whitespace after the list marker may include a newline character).

1. 
  X

  a. U
  b. V
  c. W

2. Y
3. Z

This is tested with Docutils and should work with Sphinx, too. Other implementations may show different results.

Laoag