Python 文档字符串中段落后的项目符号列表有时不适用于 sphinx 和 numpydoc

Question

使用 numpy 样式记录 Python 模块并使用 sphinx 和 numpydoc 扩展生成 html 文档，我偶然发现了有关项目符号列表的错误（或功能？）。

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.

这避免了解析错误，但仍然没有回答为什么的问题:-)

Answer 1

第一个例子实际上是一个定义列表:

定义列表由以下部分组成：

term: 
  a one-line word or phrase, and a
   
definition:
  a block indented relative to the term.

术语行和定义块之间不能有空行（这将定义列表与块引用区分开来）。 定义块可以由任何body元素组成 （包括任何类型的列表）。

第二个示例失败，因为术语不能分布在两行上，并且段落后面不能跟缩进块而不分隔空行。

第三个示例实际上是一个带有 block-quote 的段落，其中包含嵌套列表。这通常不是您的意思，它会导致输出中的列表缩进太多（参见Docutils FAQ）。