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

时间:2016-07-13 09:39:03

标签: python-sphinx restructuredtext numpydoc

使用numpy样式记录Python模块并使用sphinxnumpydoc扩展名生成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 reference,项目符号列表在它们之前和之后需要一个空行。

因此我想知道:为什么第一个版本有效(虽然它不应该),以及第二个版本(不工作)的不同之处是什么?

编辑:

在生成的html中,第一个和最后一个版本的外观不同。如果需要子弹列表没有前导空行的外观(html中的空间较少),则可以使用quickfix

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.

这可以避免解析错误,但仍然无法回答为什么的问题: - )

0 个答案:

没有答案