域¶

在 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: 标志。）

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

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`.

交叉引用语法¶

对于域提供的交叉引用角色，存在与一般交叉引用相同的交叉引用修饰符。简而言之

您可以提供显式标题和引用目标： :py:mod:`mathematical functions <math>` 将引用 math 模块，但链接文本将是“mathematical functions”。
如果您在内容前加上感叹号 (!)，则不会创建引用/超链接。
如果您在内容前加上 ~，则链接文本将仅是目标的最后一个组件。例如，:py:meth:`~queue.Queue.get` 将引用 queue.Queue.get，但仅显示 get 作为链接文本。

内置域¶

以下域包含在 Sphinx 中

本页目录

域¶

基本标记¶

交叉引用语法¶

内置域¶

更多域¶