域¶

新增于版本 1.0。

最初，Sphinx 的设计目标是针对单个项目，即 Python 语言文档。不久之后，它作为一种文档工具面向所有人开放，但 Python 模块的文档仍然深度内置 - 最基本指令，比如 function，都是为 Python 对象设计的。由于 Sphinx 变得相当流行，人们对将其用于各种用途的兴趣日益浓厚：C/C++ 项目、JavaScript，甚至是 reStructuredText 标记（就像本文档）。

虽然这始终是可行的，但现在通过为每个目的提供一个 **域**，可以更容易地支持使用不同编程语言甚至不受 Sphinx 主要发行版支持的语言的项目的文档。

域是标记（reStructuredText 指令和角色）的集合，用于描述和链接到属于一起的对象，例如编程语言的元素。域中的指令和角色名称具有 domain:name 形式，例如 py:function。域还可以提供自定义索引（如 Python 模块索引）。

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

本节描述了 Sphinx 附带的域所提供的功能。域 API 也有文档记录，在域 API 部分。

基本标记¶

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

一个域通常会保留一个所有实体的内部索引来帮助交叉引用。通常，它还会在显示的通用索引中添加条目。如果你想阻止在显示的索引中添加条目，可以为指令选项标记提供 :no-index-entry:。如果你想将对象描述从目录中排除，可以为指令选项标记提供 :no-contents-entry:。如果你想排版对象描述，甚至不使其可供交叉引用，可以为指令选项标记提供 :no-index:（意味着 :no-index-entry:）。如果你不想排版任何内容，可以为指令选项标记提供 :no-typesetting:。这可以用作例如只为以后引用创建目标和索引条目。不过，请注意，并非每个域中的每个指令都可能支持这些选项。

新增于版本 3.2: Python、C、C++ 和 Javascript 域中的指令选项 noindexentry。

新增于版本 5.2.3: Python、C、C++、Javascript 和 reStructuredText 域中的指令选项 :nocontentsentry:。

新增于版本 7.2: Python、C、C++、Javascript 和 reStructuredText 域中的指令选项 no-typesetting。

更改于版本 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。（注意，当签名变得过长时，如果在下一行继续的行的末尾添加反斜杠，你可以将它们换行。示例

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

(此示例还展示了如何使用 :no-index: 标记。）

域还提供将这些对象描述链接回的 roles。例如，要链接到示例中描述的函数之一，你可以说

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

如你所见，指令和 roles 名称都包含域名称和指令名称。

指令选项 :no-typesetting: 可用于创建目标（和索引条目），这些目标（和索引条目）以后可以通过域提供的 roles 引用。这对于可读性编程特别有用

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

.. code:: python

   def spam(eggs):
       pass

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

默认域

对于仅描述来自单个域的对象的文档，作者无需在每个指令、角色等中再次说明其名称…，而是在指定默认值后即可。这可以通过 config 值 primary_domain 或通过此指令来完成

.. default-domain:: name¶: 选择一个新的默认域。虽然 primary_domain 选择全局默认值，但这仅对同一文件内的内容有效。

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

属于默认域的指令和 roles 可以不给出域名称，即

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

交叉引用语法¶

对于域提供的交叉引用 roles，与一般交叉引用具有相同的设施。请参见交叉引用语法。

简而言之

你可以提供明确的标题和引用目标：:role:`title <target>` 将引用目标，但链接文本将是标题。
如果你在内容前面加上 !，则不会创建引用/超链接。
如果你在内容前面加上 ~，链接文本将仅是目标的最后一个组成部分。例如，:py:meth:`~Queue.Queue.get` 将引用 Queue.Queue.get，但仅显示 get 作为链接文本。

内置域¶

以下域包含在 Sphinx 中

本页内容

域¶

基本标记¶

交叉引用语法¶

内置域¶

更多域¶