术语表¶

builder¶

一个继承自 Builder 的类,它接受解析的文档并对它们执行一个动作.通常,构建器将文档转换为输出格式,但也可以使用例如检查文档中是否存在断开的链接,或构建覆盖率信息的构建器.

有关 Sphinx 内置构建器的概述,请参见构建器.

配置目录¶

包含 conf.py 的目录.默认情况下,这与源目录相同,但可以使用 -c 命令行选项设置为不同.

指令¶

一个允许用特殊含义标记内容块的 reStructuredText 标记元素.指令不仅由 docutils 提供,Sphinx 和自定义扩展也可以添加它们自己的指令.基本指令语法如下所示:

.. directive-name:: argument ...
   :option: value

   Content of the directive.

更多信息请参见指令.

文档名称¶

由于 reStructuredText 源文件可以有不同的扩展名（有些人喜欢 .txt,有些人喜欢 .rst – 扩展名可以通过 source_suffix 配置）,不同的操作系统有不同的路径分隔符,Sphinx 对它们进行了抽象:文档名称 始终相对于源目录,扩展名被去掉,路径分隔符被转换为斜杠.所有涉及”文档”的值、参数等都期望这样的文档名称.

文档名称的示例有 index、library/zipfile 或 reference/datamodel/types.请注意,没有前导或尾随斜杠.

domain¶

域是一组标记（reStructuredText 指令和角色）,用于描述和链接属于一起的对象,例如编程语言的元素.域中的指令和角色名称类似于 domain:name,例如 py:function.

拥有域意味着当一组文档想要引用例如C++和Python类时,不会出现命名问题.这也意味着支持全新语言文档的扩展更容易编写.

更多信息,请参考域.

environment¶

一个保存根目录下所有文档信息并用于交叉引用的结构.环境在解析阶段后被序列化,因此连续运行只需要读取和解析新文档和更改的文档.

扩展¶

一个自定义的角色、指令或其他允许用户在Sphinx中修改构建过程任何方面的Sphinx特性.

更多信息,请参考扩展.

主文档¶

包含根 toctree 指令的文档.

根文档¶

与主文档相同.

对象¶

Sphinx 文档的基本构建块.每个”对象指令”（例如 py:function 或 object）创建这样一个块;并且大多数对象可以交叉引用.

RemoveInSphinxXXXWarning¶

在 Sphinx-XXX 版本中将被移除的功能会发出警告.这通常是由于使用已弃用的 Sphinx 扩展引起的.另请参见何时显示弃用警告.

role¶

一个允许标记一段文本的 reStructuredText 标记元素.像指令一样,角色是可扩展的.基本语法看起来像这样::rolename:`content`.详情请参见行内标记.

源目录¶

包含所有Sphinx项目源文件的目录及其子目录.

reStructuredText¶

一种易于阅读、所见即所得的纯文本标记语法和解析器系统.