术语
- builder(生成器)
一个解析文档并执行对它们的操作的类(继承自 Builder)。通常,生成器把文档转换成输出的格式,不过,也能够使用生成器完成其他的事情:例如检查文档里的链接是否损坏,或者生成覆盖率信息。
请看 Available builders 对Sphinx的内置的生成器有个更详细的了解。
- configuration directory(配置文件目录)
- 包含 conf.py 的目录。默认是与 source directory 一样,但是能够通过命令行参数 -c 设置成不同的目录。
- directive(指令或者标识符)
允许以特定含义标记内容块的reStructuredText标记元素。指令(标识符)不仅仅对docutils模块有用,而且Sphinx以及扩展也能够添加自己的指令(标识符)。最基本的指令(标识符)的格式如下:
.. directivename:: argument ... :option: value 指令(标识符)的内容。
更加详细的信息请查看 指令(标识符) 。
- document name(文件名)
因为reST源文件可以有不同的扩展名(有的喜欢 .txt,有的喜欢 .rst –扩展名能够通过 source_suffix 配置。),同样不同的操作系统有不同的路径分隔符,Sphinx能够转换分隔符:document names 总是相对于 source directory,文件扩展名被去除,路径分隔符被转换成斜线。所有的值,参数以及所谓为“文件”都要求这样的文件名。
index, library/zipfile, 或者 reference/datamodel/types 就是文件名的例子。请注意,没有开头或结尾的斜线。
- domain(域)
域是标记的集合(reStructuredText directive 的以及 role 的),它是为了描述和链接到 object 的集合,比如程序语言的元素集。指令(标识符)以及角色(role)在域(domain)中的名称像 domain:name ,比如 py:function。
域(domain)的存在意味着不存在命名的问题当一堆文件需要引用的时候:例如C++和Python的类。这也意味着,全新的语言支持文件的扩展,更容易编写。关于域的更多的信息,请看章节 Sphinx Domains。
- environment(暂时找不到合适的词语来翻译)
- environment保存了根目录下的所有文件,用于交叉引用。它是在解析步骤后被使用,使连续运行只需要读取以及解析新的以及更新的文档。
- master document(主文件)
- 包含根指令(标识符) toctree 的文档。
- object(对象)
- Sphinx文档的基本构建块。每一个“对象指定(标识符)” (e.g. function or object)创建这样一个块;大多数的对象是能够交叉引用的。
- role(角色)
- 允许标记的一段文字的reStructuredText标记元素。跟指令(标识符)一样,属于可扩展的。基本的格式像这样::rolename:content 。详细的内容请参看 行内标记 。
- source directory(源目录)
- 包含了一个Sphinx项目的所有源文件的目录以及它所有的子目录。