Glossary¶
- builder
A class (inheriting from
Builder
) that takes parsed documents and performs an action on them. Normally, builders translate the documents to an output format, but it is also possible to use the builder builders that e.g. check for broken links in the documentation, or build coverage information.See Available builders for an overview over Sphinx’s built-in builders.
- configuration directory
- The directory containing
conf.py
. By default, this is the same as the source directory, but can be set differently with the -c command-line option. - directive
reStructuredText标记元素,允许标记具有特殊含义的内容块。指令不只是由docutils提供,Sphinx和自定义扩展可以添加自己的指令。基本指令语法如下所示:
.. directivename:: argument ... :option: value Content of the directive.
有关详细信息,请参见指令。
- document name
Since reST source files can have different extensions (some people like
.txt
, some like.rst
– the extension can be configured withsource_suffix
) and different OSes have different path separators, Sphinx abstracts them: document names are always relative to the source directory, the extension is stripped, and path separators are converted to slashes. All values, parameters and such referring to “documents” expect such document names.Examples for document names are
index
,library/zipfile
, orreference/datamodel/types
. Note that there is no leading or trailing slash.- domain
标记域是用于描述和链接属于一起的对象的标记(reStructuredText指令和角色)的集合,例如编程语言中的元素。标记域中的指令和角色的名称类似于
domain:name
,例如py:function
。具有标记域意味着当一组文档想要引用例如C++和Python类时,没有命名问题。这也意味着更容易编写支持全新语言文档的扩展。有关标记域的更多信息,请参见Sphinx标记域一章。
- environment
- A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.
- master document
- The document that contains the root
toctree
directive. - object
- Sphinx文档的基本构建块。每个“对象指令”(例如
function
或object
)创建这样一个块;并且大多数对象可以被交叉引用。 - role
- 一个允许标记一段文本的reStructuredText标记元素。和指令一样,角色是可扩展的。基本语法如下:
:rolename:`content`
。有关详细信息,请参阅内联标记。 - source directory
- The directory which, including its subdirectories, contains all source files for one Sphinx project.