指令在呈现的文档中显示为文字文本

Question

我想在几个部分 headers 之间显示两个函数的文档字符串，如下所示：

===
API
===

.. autofunction:: parsons.aws.distribute_task

.. autofunction:: parsons.aws.event_command

***
S3
***

两个文档字符串都出现在呈现的 HTML 中，但第二个函数也将 Sphinx 指令 .. autofunction:: parsons.aws.event_command 显示为文档字符串下方的文本：

关于为什么会发生这种情况以及如何摆脱它的任何想法？

您可以在 GitHub 上的文件顶部看到问题（以及该项目的所有代码）：

https://github.com/move-coop/parsons/blob/master/docs/aws.rst

并且在内置版本的文档中：

https://move-coop.github.io/parsons/html/aws.html

Answer 1

GitHub 上的代码没有空行分隔两个 .. autofunction:: 指令：

.. autofunction :: parsons.aws.distribute_task
.. autofunction :: parsons.aws.event_command

reStructuredText rules for directives 表示：

Actions taken in response to directives and the interpretation of text in the directive content block or *subsequent text block(s) are directive-dependent.

所以看看“语法图”，以及指令块的“三个逻辑部分”：

There are three logical parts to the directive block:

    Directive arguments.
    Directive options.
    Directive content.

(...)

Syntax diagram:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

对我而言，“后续文本块”（将具有依赖于指令的行为）是否适用于紧跟在另一个指令之后的指令或仅适用于"指令块的三个逻辑部分".

指令算作 Explicit Markup Block，因此第三条规则意味着指令应该在未缩进的行之前结束。

An explicit markup block is a text block: (...)

which ends before an unindented line.

请注意，两个 .. autofunction:: 指令之间没有明确的结尾（均未缩进）。进一步说明：

Blank lines are required between explicit markup blocks and other elements, but are optional between explicit markup blocks where unambiguous.

在指令后留空行通常更安全，以防止任何未指定的行为（在您的情况下，让指令正常呈现并以文本形式包含）。

如果您在指令后留一个空行，它应该会按预期工作。

编辑： this old style guide 提到在上划线部分之前应放置 2 个空行。我无法解释原因（可能是 GitHub 或 readthedocs 本地问题）但显然它解决了问题。

指令在呈现的文档中显示为文字文本

directive appearing as literal text in rendered document

python

restructuredtext

sections

python-sphinx

autodoc