Documenting a Python module using the numpy style and generating html documentation using sphinx and the numpydoc extension, I stumbled upon a bug (or feature?) regarding bulleted lists.
In reStructuredText (and sphinx/numpydoc), a single-lined paragraph
- with an immediately following
- bullet list
- is allowed,
but if you have a "long" paragraph,
which may be spanning several lines,
- a following bullet list
- results in an `ERROR: Unexpected indentation`.
With a blank line added between the "long" paragraph, which again
may span multiple lines, and the following list,
- bullet lists
- work fine again.
According to the reStructuredText reference, bullet lists require an empty line before and after them.
Therefore I'd like to know: Why does the fist version work (while it shouldn't), and what is so different to the (not working) second version?
Edit:
In generated html the first and the last version differ in appearance. If the look of the bullet list without a leading empty line is desired (less space in html), a quickfix could be
to escape every line break by a backslash.\
This way there's effectively only a single long line,
- which allows bullet lists
- even after long paragraphs.
This avoids the parsing error, but still does not answer the question of why :-)
