域¶

Added in version 1.0.

最初,Sphinx是为了一个单一项目而构思的,即Python语言的文档.此后,它作为文档工具向所有人开放,但Python模块的文档仍然深深内嵌 - 最基本的指令,如 function ,是为Python对象设计的.随着Sphinx变得相对受欢迎,人们开始对其用于许多不同目的产生兴趣:C/C++项目、JavaScript,甚至reStructuredText标记（如本文件中的内容）.

虽然这一直是可能的,但现在通过为每个目的提供一个**域**,文档支持不同编程语言甚至是主Sphinx发行版不支持的项目变得更加容易.

A domain is a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like domain:name, e.g. py:function. Domains can also provide custom indices (like the Python Module Index).

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

本节描述了Sphinx中包含的域所提供的内容.域API的文档也在: ef:domain-api 部分中记录.

基本标记¶

大多数领域提供了一些 对象描述指令 ,用于描述模块提供的特定对象.每个指令需要一个或多个签名,以提供关于所描述内容的基本信息,内容应为描述.

一个域通常会保持一个内部索引记录所有实体,以帮助交叉引用.通常,它还会在显示的通用索引中添加条目.如果您想要抑制在显示的索引中添加条目,可以给出指令选项标志 :no-index-entry: .如果您想要从目录中排除对象描述,可以给出指令选项标志 :no-contents-entry: .如果您想要排版对象描述,而不使其可用于交叉引用,可以给出指令选项标志 :no-index: （这意味着 :no-index-entry: ）.如果您不想排版任何内容,可以给出指令选项标志 :no-typesetting: .这可以用来仅创建一个目标和索引条目,以便稍后参考.不过,请注意,并非每个域中的每个指令都可能支持这些选项.

Added in version 3.2: Python、C、C++和Javascript领域中的指令选项 noindexentry .

Added in version 5.2.3: Python、C、C++、Javascript 和 reStructuredText 域中的指令选项 :nocontentsentry: .

Added in version 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`.

交叉引用语法¶

对于由域提供的交叉引用角色,提供的功能与一般交叉引用相同.请参见交叉引用语法 .

简而言之:

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

内置域¶

以下域包含在Sphinx中:

On this page

域¶

基本标记¶

交叉引用语法¶

内置域¶

更多域¶