领域

Added in version 1.0.

最初，sphinx是为一个项目而设计的，即Python语言的文档。不久之后，它作为一个文档工具被提供给了每个人，但是Python模块的文档仍然是深入内置的——最基本的指令，比如 function ，是为Python对象设计的。由于Sphinx已经变得有点受欢迎，所以在使用它时有很多不同的兴趣：C/C++项目、JavaScript、甚至RealStReWorkType标记（如本文中的文档）。

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

域是标记（RestructuredText）的集合 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++域、Java脚本域和reStrucredText域中。

Added in version 7.2: 指令选项 no-typesetting 在Python域、C、C++域、Java脚本域和reStrucredText域中。

在 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::

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

交叉引用语法

对于域提供的交叉引用角色，存在与一般交叉引用相同的工具。见 交叉引用语法 .

简而言之：

  • 您可以提供明确的标题和参考目标： :role:`title <target> “将指 目标 ，但链接文本将 标题 .

  • 如果在内容前面加上前缀 ! ，不会创建引用/超链接。

  • 如果在内容前面加上前缀 ~ ，链接文本将仅是目标的最后一个组件。例如， :py:meth:`~Queue.Queue.get “将指 Queue.Queue.get 但只显示 get 作为链接文本。

内置域

Sphinx中包括以下域：

更多领域

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