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

Question

我想在几个节标题之间显示两个函数的文档字符串，如下所示：

===
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 声明：

为响应指令而采取的操作以及指令内容块或*后续文本块中的文本解释取决于指令。

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

There are three logical parts to the directive block:

    Directive arguments.
    Directive options.
    Directive content.

(...)

Syntax diagram:

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

对我来说，“后续文本块”（将具有指令相关行为）适用于紧跟在另一个指令之后的指令还是仅适用于 “三个指令块的逻辑部分".

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

显式标记块是文本块： (...)

• 在未缩进的行之前结束。

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

显式标记块和其他元素之间需要空行，但在明确标记块之间是可选的。

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

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

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