Python：Sphinx不输出转换

Question

我正在使用Sphinx记录我正在编写为网页的软件包。包的每个成员都有一个文档字符串，我使用autosummary自动将其转换为单独的rst文件。

我的问题是，我无法使用转场在html输出中打印水平线（通过使用----）。每当我添加其中之一时，Sphinx都会输出错误消息，并且生成的html不包含过渡。

这里是一个最小的例子。以下功能属于my_module。

def foobar():
    r"""Foo

    ----

    Bar
    """
    pass

这是我的Sphinx的主要index.rst文件：

.. autosummary::
    :toctree: _api_members

    my_module.foobar

尝试制作html将输出以下消息：

docstring of my_module.foobar:3: WARNING: Unexpected section title or transition.

并且如下所示，输出不包含预期的过渡。

我发现解决此问题的唯一方法是使用原始html打印<hr>，但这确实是对文档字符串造成污染的不雅解决方案。

def foobar():
    r"""Foo

    .. raw:: html

        <hr>

    Bar
    """
    pass

使用水平规则产生期望的输出：

我相信我对默认conf.py所做的唯一更改是：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
]

autosummary_generate = True
autosummary_imported_members = True

所以我的问题是，如何在html输出中打印水平规则，而不必将原始html代码手动添加到我的文档字符串中？

Answer 1

根据我收集的信息，尝试将部分或过渡放在docstring 'Unexpected Section Title' with Sphinx 中不是一个好策略。

还请注意，如何重新设置过渡取决于您使用的主题或自定义CSS的方式。不同的主题可能会产生非常不同的结果。

关于此问题有多个主题，或多或少都说相同：它不能很好地工作，并且会引起问题。

一种解决方案是不要在文档字符串的整个高度中使用转场/节，而仅将其用于.rst文件。这样做的结果是，autosummary指令可能无法“自动”构建所需的toctree。但是，通过这种方式，您将必须在toctree中显式地构造.rst和部分，从而最终可以更好地总体控制演示和渲染。