域¶

Added in version 1.0.

最初，Sphinx是为一个项目而设计的，即Python语言的文档。不久之后，它作为文档工具提供给每个人，但Python模块的文档仍然深入构建--最基本的指令，比如 function ，是为Python对象设计的。由于Sphinx变得有些受欢迎，人们对将其用于许多不同目的的兴趣逐渐浓厚：C/C++项目、JavaScript，甚至reStructuredtext标记（如本文档中所示）。

虽然这始终是可能的，但现在通过提供 domain 为了每一个这样的目的。

域是标记（reStructured文本）的集合 directive s和 role s）描述并链接到 object 属于一起，例如编程语言的元素。域中的指令和角色名称的名称如下 domain:name ，例如： py:function . 域还可以提供自定义索引（例如Python模块索引）。

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

本节描述Sphinx包含的域提供的内容。域API也在部分中记录了域名API .

基本标记¶

大多数域名提供多种 object description directives ，用于描述模块提供的特定对象。每个指令都需要一个或多个签名来提供有关所描述内容的基本信息，并且内容应该是描述。

域通常会保留所有实体的内部索引，以帮助交叉引用。通常，它还将在所示的常规索引中添加条目。如果你想禁止在显示的索引中添加一个条目，你可以给指令选项标志 :no-index-entry: .如果你想从目录中排除对象描述，你可以给指令选项标志 :no-contents-entry: .如果您想对对象描述进行打字，甚至不使其可用于交叉引用，则可以赋予指令选项标志 :no-index: （这意味着 :no-index-entry: ).如果您不想打字任何内容，可以赋予指令选项标志 :no-typesetting: . 例如，这可以用于仅创建目标和索引条目以供稍后引用。不过，请注意，并非每个域中的每个指令都可能支持这些选项。

Added in version 3.2: 指令选项 noindexentry 在Python、C、C++和JavaScript领域。

Added in version 5.2.3: 指令选项 :nocontentsentry: 在Python、C、C++、JavaScript和reStructuredText域中。

Added in version 7.2: 指令选项 no-typesetting 在Python、C、C++、JavaScript和reStructuredText域中。

在 7.2 版本发生变更:

指令选项 :noindex: 更名为 :no-index: .
指令选项 :noindexentry: 更名为 :no-index-entry: .
指令选项 :nocontentsentry: 更名为 :no-contents-entry: .

以前的名称将保留为别名，但在Sphinx的未来版本中将被废弃并删除。

使用Python域指令的示例：：

.. py:function:: spam(eggs)
                 ham(eggs)

   Spam or ham the foo.

这描述了两个Python函数 spam 和 ham . (Note当签名变得太长时，如果您在下一行中继续的行中添加反斜线，则可以将其打断。示例：：

.. py:function:: filterwarnings(action, message='', category=Warning, \
                                module='', lineno=0, append=False)
   :no-index:

(This示例还展示了如何使用 :no-index: 旗帜。）

这些域还提供链接回这些对象描述的角色。例如，要链接到上面示例中描述的功能之一，您可以说：：

The function :py:func:`spam` does a similar thing.

如您所见，指令名称和角色名称都包含域名和指令名称。

指令选项 :no-typesetting: 可用于创建目标（和索引条目），稍后可以由域提供的角色引用该目标。这对于识字编程特别有用：

.. py:function:: spam(eggs)
   :no-typesetting:

.. code:: python

   def spam(eggs):
       pass

The function :py:func:`spam` does nothing.

默认域

对于描述仅来自一个域的对象的文档，作者不必在每个指令、角色等处再次声明其名称.指定默认值后。这可以通过配置值来完成 primary_domain 或通过此指令：

.. default-domain:: name¶: 选择新的默认域。而 primary_domain 选择一个全局默认值，这只在同一个文件中有效。

如果未选择其他默认值，则Python域（名为 py ）是默认的，主要是为了与为旧版本的Sphinx编写的文档兼容。

可以提及属于默认域的指令和角色，而无需给出域名，即：：

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

交叉引用语法¶

对于域提供的交叉引用角色，相同 cross-referencing modifiers 与一般交叉引用一样存在。简而言之：

您可以提供明确的标题和引用目标： :py:mod:`mathematical functions <math> '将指的是 math 模块，但链接文本将是“数学函数”。
如果您在内容前面加上感叹号 (! ），不会创建引用/超链接。
如果您在内容前加上 ~ ，链接文本将只是目标的最后一个组成部分。例如， :py:meth:`~queue.Queue.get '将指的是 queue.Queue.get 只显示 get 作为链接文本。

内置域名¶

Sphinx包含以下域名：

多个结构域¶

有几个第三方域名可作为扩展，包括：