域¶
Added in version 1.0.
最初，Sphinx是为单个项目构思的，即Python语言的文档。不久之后，它作为一个文档工具开放给每个人，但Python模块的文档仍然内置 —— 最基本的指令，如“function”，是为Python对象设计的。由于Sphinx在某种程度上变得流行起来，人们对将它用于许多不同目的产生了兴趣：C/ c++项目、JavaScript，甚至是重构文本标记（如本文档中所示）。
虽然这一直都是可能的，但是现在，通过为每种目的提供一个**域**，可以更容易地支持使用不同编程语言（甚至是主Sphinx发行版不支持的语言）的项目文档。
域是一组标签（reStructuredText directives and roles），用于描述和链接 objects ，属于一起，例如编程语言的元素。域中的指令和角色名称具有诸如 domain:name 之类的名称，例如 py:function 。域还可以提供自定义索引(例如Python模块索引)。一个域是一个标记的集合（reStructuredText 指令 and 角色），用来描述和链接属于一起的 对象 ，例如编程语言的元素。域中的指令名和角色名有如下名称“domain:name”，例如“py:function”。域还可以提供自定义索引（如Python 模块索引）。
拥有域意味着当一组文档引用（例如c++和Python类）时不会出现命名问题。这还意味着支持全新语言文档的扩展更容易编写。
本节描述Sphinx包含的域提供了什么。域API也被记录在 :ref:`domain-api`一节中。
基本标记¶
Most domains provide a number of object description directives, used to describe specific objects provided by modules. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be the description.
A domain will typically keep an internal index of all entities to aid
cross-referencing.
Typically it will also add entries in the shown general index.
If you want to suppress the addition of an entry in the shown index, you can
give the directive option flag :no-index-entry:.
If you want to exclude the object description from the table of contents, you
can give the directive option flag :no-contents-entry:.
If you want to typeset an object description, without even making it available
for cross-referencing, you can give the directive option flag :no-index:
(which implies :no-index-entry:).
If you do not want to typeset anything, you can give the directive option flag
:no-typesetting:. This can for example be used to create only a target and
index entry for later reference.
Though, note that not every directive in every domain may support these
options.
Added in version 3.2: 指令选项“`noindexentry”在Python、C、C++和Javascript域。
Added in version 5.2.3: The directive option :nocontentsentry: in the Python, C, C++, Javascript,
and reStructuredText domains.
Added in version 7.2: The directive option no-typesetting in the Python, C, C++, Javascript,
and reStructuredText domains.
在 7.2 版本发生变更:
The directive option
:noindex:was renamed to:no-index:.The directive option
:noindexentry:was renamed to:no-index-entry:.The directive option
:nocontentsentry:was renamed to:no-contents-entry:.
The previous names are retained as aliases, but will be deprecated and removed in a future version of Sphinx.
使用Python域指令的一个例子:
.. py:function:: spam(eggs)
ham(eggs)
Spam or ham the foo.
这描述了两个Python函数‘spam’和‘ham’。(请注意，当签名太长时，如果在下一行继续的行中添加一个反斜杠，可以将其断开。例如:
.. py:function:: filterwarnings(action, message='', category=Warning, \
module='', lineno=0, append=False)
:no-index:
(This example also shows how to use the :no-index: flag.)
域还提供链接回这些对象描述的角色。例如，要链接到上面示例中描述的其中一个函数，您可以说：
The function :py:func:`spam` does a similar thing.
如您所见，指令和角色名称都包含域名和指令名称。
The directive option :no-typesetting: can be used to create a target
(and index entry) which can later be referenced
by the roles provided by the domain.
This is particularly useful for literate programming:
.. py:function:: spam(eggs)
:no-typesetting:
.. code::
def spam(eggs):
pass
The function :py:func:`spam` does nothing.
默认域
对于仅从一个域描述对象的文档，作者在指定默认值后，不必再在每个指令，角色等处再次声明其名称。这可以通过配置值:confval:`primary_domain`或通过此指令来完成：
如果没有选择其他默认值，则Python域(名为“py”)是默认值，主要是为了与为旧版Sphinx编写的文档兼容。
属于默认域的指令和角色可以在不给出域名的情况下被提及，即:
.. function:: pyfunc()
Describes a Python function.
Reference to :func:`pyfunc`.
交叉引用语法¶
对于域提供的交叉引用角色，存在与一般交叉引用相同的工具。请参阅 交叉引用语法 。
简而言之:
您可以提供一个明确的标题和引用目标：“:role:`title <target>”将指向*target*，但是链接文本将是*title*。
如果在内容前加上“！” ，则不会创建引用或超链接。
如果在内容前面添加“~”，则链接文本将只是目标的最后一个组件。例如，
get()将引用 “Queue.Queue.get ”但仅显示“ get ”作为链接文本。
Built-in domains¶
The following domains are included within Sphinx:
更多域¶
There are several third-party domains available as extensions, including: