Списки маркеров после абзаца в Python Docstring иногда не работают со сфинксом и numpydoc
Документируя модуль Python с использованием стиля numpy и генерируя html-документацию с использованием sphinx и расширения numpydoc, я наткнулся на ошибку (или функцию?) В маркированных списках.
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.
Согласно ссылке reStructuredText, списки маркеров требуют пустой строки до и после них.
Поэтому я хотел бы знать: почему первая версия работает (хотя она не должна), и чем она отличается (не работает) от второй версии?
Редактировать:
В сгенерированном html первая и последняя версии отличаются по внешнему виду. Если желателен внешний вид списка маркеров без пустой строки в начале (меньше места в html), быстрое исправление может быть
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.
Это позволяет избежать ошибки синтаксического анализа, но все равно не отвечает на вопрос, почему:-)