Nested <UL> lists are not correctly parsed about guides HOT 10 CLOSED

I guess you mean OL everywhere you say UL 😉

To make it more interesting: when I add whitelines, suddenly I do not get a DL, but a blockquote around the nested UL :)

This sounds expected to me (in relation to the bug described before). The only difference, syntactically, between a blockquote and a definition list is a blank line between the unindented and indented line in reSt.
As example 1 is recognized as definition list, it makes sense example 2 is recognized as blockquote.

from guides.

If I check https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks, then the one with the whitelines should be correct; but let me check if we are really strict about the indentation and that is why I get a block quote

from guides.

Ah yes, I see that number of spaces indentation is quite strict :D

#. 1st level of nesting

    #. Second level of nesting

#. 1st level of nesting again

Will give a block quote and then a list because I used 4 spaces for the indent of the sub-ol; if I do this:

#. 1st level of nesting

   #. Second level of nesting

#. 1st level of nesting again

And reduce it to 3 spaces (matching the first character in the li above) then it will correctly render a regular nested list. I do wonder if the block quote should not happen when at least 2 spaces beyond the LI above to take a bit of room for error into account?

from guides.

I just threw all your examples in Sphinx and it looks like we're actually 100% spec compatible :)

Legend: red = <ol>, blue = <dl>, green = <blockquote>

from guides.

I had some issues with lists... but I'm glad @wouterj confirms that I implemented it according to spec. :-D

A good thing to notice is that the first example @mvriel gave is an invalid list. List MUST preceded by 1 or more whitelines. And MUST be followed by 1 or more white lines.

The second level of indenting must be exactly at the level of indenting of the first element line to start. otherwise, we will detect it as a blockquote because that's only recognized by an indentation of 2 or more spaces.

from guides.

The second level of indenting must be exactly at the level of indenting of the first element line to start. otherwise, we will detect it as a blockquote because that's only recognized by an indentation of 2 or more spaces.

In the example below, the indentation is one space when you compare it to the nesting indent right?

#. 1st level of nesting

    #. Second level of nesting

#. 1st level of nesting again

Here the second level of nesting is 1 space indented from the indentation level of the previous; and from a DX perspective I could more or less say that adding support for level+1 when it comes to nested lists will give less headache. When I use tab to indent, it will become 4 spaces instead of 3; and this is an easy mistake to make :)

from guides.

I'm not aware of the 2 spaces rule, afaik the spec always talk about "indented lines" by which they mean "at least 1 space more than the current indentation level".

I would be in favor of strictly following Sphinx/reStructuredText, rather than improving upon them (for one, to make a transition easier for projects that still use Sphinx). I agree that indentation in reStructuredText is a bit of a bad DX - I've had to fix it multiple times in the Symfony docs as well - but that's an issue of the spec, and not this parser imho.

from guides.

There is no rule based on the spec on that, the spec is vague about that and talks about 'the level of indentation needs to be consistent' (https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#indentation). I, for one, take this with a slight grain of salt because if I am really strict about it, we'd need to detect/define the indentation and fail every location that does not match that exact number. And I do not believe that to be good DX :)

The 2 spaces rule of thumb is what I generally apply in these situations because few people indent with 1 space, and I make an assumption that a single space deviation is more of an inconsistency/spacing error. By incorporating that into a parser we can be 'nice' to the user :)

Though, please close this issue if the consensus is not to consider this. I am just giving an opinion now and feel perfectly comfortable with closing this issue

from guides.

@wouterj should we add tests for all described scenarios? I would really love if creating block-comments by indentation could be prevented by configuration. These stupid block-comments cause us problems all over in the docs and there is an explicit directive if you really have to make a block-comment (we rarely use them by indent intent)

from guides.

it's fairly easy to make them optional... due to the current design of the parser you could just reconfigure the parser without the block-comments production.
I think that's enough to leave them out.

from guides.