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

问题描述

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

===
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

解决方法

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本地问题），但显然可以解决问题。