字段列表¶

如前所述，字段列表是按如下方式标记的字段序列

:fieldname: Field content

Sphinx 扩展了标准 docutils 字段列表的行为，并添加了本节介绍的一些额外功能。

注意

字段列表的值将作为字符串解析。您不能使用 Python 集合，如列表或字典。

文件范围元数据¶

文件顶部的字段列表通常由 docutils 解析为 文档信息 并显示在页面上。然而，在 Sphinx 中，任何其他标记之前的字段列表会从 文档信息 移动到 Sphinx 环境中作为文档元数据，并且不会显示在输出中。

注意

文档标题后出现的字段列表将像往常一样成为 文档信息 的一部分，并将在输出中显示。

与 docutils 相比，Sphinx 为书目字段提供了自定义行为。

目前，识别以下元数据字段

tocdepth

此文件目录的最大深度。

:tocdepth: 2

注意

此元数据影响本地 toctree 的深度。但它不影响全局 toctree 的深度。因此，这不会改变使用全局 toctree 的主题的侧边栏。

版本 0.4 新增。

nocomments

如果设置，Web 应用程序将不会为此源文件生成的页面显示评论表单。

:nocomments:

orphan

如果设置，将抑制有关此文件未包含在任何 toctree 中的警告。

:orphan:

版本 1.0 新增。

no-search

禁用此文档的全文搜索。

:no-search:

注意

:no-search: 选项仅禁用全文搜索，这意味着即使设置了 :no-search:，对象搜索仍然可用。

3.0 版本新增。

7.3 版本更改: 文件范围元数据选项 :nosearch: 已重命名为 :no-search:。旧名称已保留作为别名，但将在 Sphinx 的未来版本中弃用并移除。