指令在渲染文档中显示为文字文本

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 规则 指出：响应指令而采取的操作以及指令内容块或*后续文本块中的文本解释取决于指令。因此，查看“语法图”和指令块的“三个逻辑部分” ：There are three logical parts to the directive block:    Directive arguments.    Directive options.    Directive content.(...)Syntax diagram:+-------+-------------------------------+| ".. " | directive type "::" directive |+-------+ block                         |        |                               |        +-------------------------------+对我来说，尚不完全清楚“后续文本块”（将具有指令相关行为）是否适用于紧随另一个指令的指令，或者仅适用于“指令块的三个逻辑部分”。指令算作显式标记块，因此第三条规则意味着指令应在未缩进的行之前结束。显式标记块是文本块：(...)它在未缩进的行之前结束。请注意，这两个指令之间没有明确的结尾.. autofunction::（两者都没有缩进）。进一步指出：显式标记块和其他元素之间需要空行，但在明确的标记块之间可以选择空行。通常在指令后添加空行会更安全，以防止任何未指定的行为（在您的情况下，让指令正常渲染并以文本方式包含）。如果您在指令后留下一个空行，它应该按预期工作。