域

在 1.0 版本加入.

最初，Sphinx是为单个项目(Python语言的文档)构思的。不久之后，它作为一个文档工具开放给每个人，但Python模块的文档仍然内置 —— 最基本的指令，如 function，是为Python对象设计的。由于Sphinx在某种程度上变得流行起来，人们对将它用于许多不同目的产生了兴趣：C/ C++项目、JavaScript，甚至是reStructuredText标记（如本文档中所示）。

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

域是一些标记（reStructuredText directives 和 roles）的集合，用于描述和链接属于同一类的 objects，例如编程语言的元素。域中的指令和角色名称类似于 domain:name，例如 py:function。域还可以提供自定义索引(像如Python模块索引那样)。

拥有域意味着当一组文档引用（例如c++和Python类）时不会出现命名问题。这还意味着支持全新语言文档的扩展更容易编写。

本节描述Sphinx包含的域提供了什么。域API也被记录在 域接口 一节中。

内置域

Sphinx中包含以下域：

• 标准域
• C域
• C++ 域
• JavaScript域
• 数学科学域
• Python域
• reStructuredText域

第三方域

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

• Ada

• Antlr4

• Bazel

• BibTex

• Bison/YACC

• Chapel

• CMake

• Common Lisp

• Erlang

• Fortran

• GraphQL

• Go

• HTTP

• Hy

• Lua

• MATLAB

• PHP

• Ruby

• Rust

• Verilog

• VHDL

• Visual Basic

其他域可以在Python包索引（通过 Framework :: Sphinx :: Domain 分类器），GitHub, GitLab 中找到。

基本标记

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

域通常会保留所有实体的内部索引以帮助交叉引用。通常，它还会在显示的常规索引中添加条目。如果您想抑制在显示的索引中添加条目，可以使用 :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 作为链接文本。

Previous

构建器

Next

标准域