字段列表¶

如先前讨论，字段列表是像这样标记的字段序列

:fieldname: Field content

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

注意

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

文件级元数据¶

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

注意

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

与 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 版本中将被弃用和删除。