域

1.0 新版功能.

最初，Sphinx是为单个项目构思的，即Python语言的文档。不久之后，它作为一个文档工具提供给每个人，但Python模块的文档仍然内置 - 最基本的指令，如 function ，是为Python对象设计的。由于Sphinx已经变得有些受欢迎，因此将其用于许多不同目的的兴趣: C/C++ 项目，JavaScript，甚至是reStructuredText标记(如本文档中所述)。

虽然这总是可行的，但现在通过为每个此类目的提供 domain ，可以更轻松地轻松支持使用不同编程语言的项目文档，甚至是主要Sphinx发行版不支持的项目文档。

域是一组标签(reStructuredText directives and roles)，用于描述和链接 objects ，属于一起，例如编程语言的元素。域中的指令和角色名称具有诸如 domain:name 之类的名称，例如 py:function 。域还可以提供自定义索引(例如Python模块索引)。

拥有域意味着当一组文档想要引用时，没有命名问题。 C++ 和 Python 类。这也意味着支持全新语言文档的扩展更容易编写。

本节介绍Sphinx提供的域名。域API也在以下部分中记录 域API 。

基本标记

大多数域提供了许多 object description directives ，用于描述模块提供的特定对象。每个指令都需要一个或多个签名来提供有关所描述内容的基本信息，内容应该是描述。基本版本在一般索引中生成条目;如果不需要索引条目，可以给出指令选项标志 :noindex: 。使用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)
   :noindex:

(这个例子还展示了如何使用 :noindex: 标志。)

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

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

如您所见，指令和角色名称都包含域名和指令名称。

默认域

对于仅从一个域描述对象的文档，作者在指定默认值后，不必再在每个指令，角色等处再次声明其名称。这可以通过配置值 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 作为链接文本。

Python域

Python域(名称 py )为模块声明提供以下指令:

.. py:module:: name

该指令标志着模块(或包子模块)描述的开始，在这种情况下，名称应该是完全限定的，包括包名称。它不会创建内容(例如 py:class 确实如此)。

该指令还将导致全局模块索引中的条目。

platform 选项(如果存在)是一个逗号分隔的模块可用平台列表(如果它在所有平台上都可用，则应省略该选项)。密钥是短标识符;正在使用的示例包括 “IRIX” ，”Mac” ， “Windows” 和 “Unix” 。使用已适用的密钥非常重要。

“概要”选项应包含一个描述模块用途的句子 - 它目前仅用于全局模块索引。

可以给出 deprecated 选项(没有值)将模块标记为已弃用;它将在各个地点被指定。

.. py:currentmodule:: name

该指令告诉Sphinx，这里记录的类，函数等都在给定的模块中(如 py:module)，但它不会创建索引条目，全局模块索引中的条目，或者一个链接目标 py:mod 。这在模块中的事物文档分布在多个文件或部分的情况下很有用 - 一个位置具有 py:module 指令，其他只有 py:currentmodule 。

为模块和类内容提供以下指令:

.. py:function:: name(parameters)

描述模块级功能。签名应该包含Python函数定义中给出的参数，请参阅 Python签名 。例如:

.. py:function:: Timer.repeat(repeat=3, number=1000000)

对于你应该使用的方法 py:method 。

描述通常包括有关所需参数及其使用方式的信息(特别是是否修改了作为参数传递的可变对象)，副作用和可能的异常。

这个信息可以(在任何 py 指令中)可选地以结构化形式给出，参见 信息字段列表 。

.. py:data:: name

描述模块中的全局数据，包括用作“定义的常量”的变量和值。使用此环境不记录类和对象属性。

.. py:exception:: name

描述异常类。签名可以，但不必包括带有构造函数参数的括号。

.. py:class:: name
.. py:class:: name(parameters)

描述一个类。签名可以选择包括带有参数的括号，这些参数将显示为构造函数参数。另见 Python签名 。

属于该类的方法和属性应放在此指令的主体中。如果将它们放在外面，则提供的名称应包含类名，以便交叉引用仍然有效。例:

.. py:class:: Foo

   .. py:method:: quux()

-- or --

.. py:class:: Bar

.. py:method:: Bar.quux()

第一种方式是首选方式。

.. py:attribute:: name

描述对象数据属性。描述应包括有关预期数据类型的信息以及是否可以直接更改。

.. py:method:: name(parameters)

描述对象方法。参数不应包含 self 参数。描述应该包括与 function 描述的类似的信息。另见 Python签名 和 信息字段列表 。

.. py:staticmethod:: name(parameters)

像 py:method ，但表示该方法是静态方法。

0.4 新版功能.

.. py:classmethod:: name(parameters)

像 py:method ，但表示该方法是一个类方法。

0.6 新版功能.

.. py:decorator:: name
.. py:decorator:: name(parameters)

描述装饰器功能。签名应表示作为装饰者的用法。例如，给定功能

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

描述应如下所示:

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

(而不是 .. py:decorator :: removename(func) 。)

没有 py:deco 角色链接到用这个指令标记的装饰器;相反，使用 py:func 角色。

.. py:decoratormethod:: name
.. py:decoratormethod:: name(signature)

与 py:decorator 相同，但对于作为方法的装饰器。

使用 py:meth 角色引用装饰器方法。

Python签名

函数，方法和类构造函数的签名可以像在Python中编写一样给出。

可以给出可选参数的默认值(但如果它们包含逗号，则会混淆签名解析器)。还可以给出Python 3样式的参数注释以及返回类型注释:

.. py:function:: compile(source : string, filename, symbol='file') -> ast object

对于具有可选参数但没有默认值的函数(通常在没有关键字参数支持的C扩展模块中实现的函数)，可以使用括号指定可选部分:

compile(source[, filename[, symbol]])

习惯上将开口括号放在逗号之前。

信息字段列表

0.4 新版功能.

在Python对象描述指令中，具有这些字段的reST字段列表可以很好地识别和格式化:

  • param, parameter, arg, argument, key, keyword: Description of a parameter.

  • type:参数的类型。如果可能，创建一个链接。

  • raises，raise，except，exception:那个(和什么时候)引发了一个特定的异常。

  • var, ivar, cvar: 变量的描述。

  • vartype: Type of a variable. 如果可能，创建一个链接。

  • returns, return: 返回值的描述。

  • rtype: Return type. 如果可能，创建一个链接。

注解

在当前版本中，所有 var ， ivar 和 cvar 都表示为 “Variable” 。完全没有区别。

字段名称必须包含这些关键字之一和参数(除了 returns 和 rtype ，它们不需要参数)。这可以用一个例子来解释:

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

这将呈现如下:

send_message(sender, recipient, message_body[, priority=1])

向收件人发送邮件

参数

  • sender (str) – 发送消息的人

  • recipient (str) – 邮件的收件人

  • message_body (str) – 消息的正文

  • priority (integer or None) – 消息的优先级可以是1-5

返回

消息ID

返回类型

int

引发

  • ValueError – 如果message_body超过160个字符

  • TypeError – 如果message_body不是基本字符串

如果类型是单个单词，也可以组合参数类型和描述，如下:

:param int priority: The priority of the message, can be a number 1-5

1.5 新版功能.

可以使用以下语法自动链接容器类型(如列表和词典):

:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]

如果用单词“”或“”分隔，则类型字段中的多个类型将自动链接:

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str

交叉引用Python对象

以下角色引用模块中的对象，如果找到匹配的标识符，则可能是超链接:

:py:mod:

参考模块;可以使用虚线名称。这也应该用于包名称。

:py:func:

引用Python函数;可以使用点名。角色文本不需要包括尾随括号以增强可读性;如果 add_function_parentheses 配置值为 True (默认值)，它们将由Sphinx自动添加。

:py:data:

引用模块级变量。

:py:const:

引用一个“定义的”常量。这可能是一个不打算更改的Python变量。

:py:class:

引用一个类;可以使用虚线名称。

:py:meth:

引用对象的方法。角色文本可以包括类型名称和方法名称;如果它出现在类型的描述中，则可以省略类型名称。可以使用点状名称。

:py:attr:

引用对象的数据属性。

:py:exc:

引用异常。可以使用点状名称。

:py:obj:

引用未指定类型的对象。例如有用as default_role 。

0.4 新版功能.

此标记中包含的名称可以包括模块名称和/或类名称。例如，:py:func:`filter` 可以引用当前模块中名为 filter 的函数，或者该名称的内置函数。相比之下， :py:func:`foo.filter` 清楚地引用了 foo 模块中的 filter 函数。

通常，首先搜索这些角色中的名称而不进一步限定，然后将当前模块名称添加到前面，然后使用当前模块和类名(如果有)作为前缀。如果您在名称前加一个点，则此顺序相反。例如，在Python的文档 codecs 模块中，:py:func:`open` 总是引用内置函数，而 :py:func:`.open` 指 codecs.open() 。

类似的启发式方法用于确定名称是否是当前记录的类的属性。

此外，如果名称以点为前缀，并且未找到完全匹配，则将目标作为后缀，并搜索具有该后缀的所有对象名称。例如，:py:meth:`.TarFile.close` 引用 tarfile.TarFile.close() 函数，即使当前模块不是 tarfile 。由于这可能会变得模棱两可，如果有多个可能匹配，您将收到Sphinx的警告。

请注意，您可以组合使用 ~ 和 . 前缀: :py:meth:`~.TarFile.close` 将引用 tarfile.TarFile.close() 方法，但可见的链接标题只是 close()。

C域

C域(名称 c)适用于C API的文档。

.. c:function:: function prototype

描述C函数。签名应如C所示，例如:

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

这也用于描述类似函数的预处理器宏。应该给出参数的名称，以便它们可以在描述中使用。

请注意，签名中不必使用反斜杠转义星号，因为reST内联器不会对其进行解析。

.. c:member:: declaration

描述C结构成员。签名示例:

.. c:member:: PyObject* PyTypeObject.tp_bases

描述文本应包括允许的值范围，应如何解释值以及是否可以更改值。对文本中结构成员的引用应使用 member 角色。

.. c:macro:: name

描述一个 “simple” 的C宏。简单宏是用于代码扩展的宏，但不带参数，因此不能将其描述为函数。这是一个简单的C语言 #define 。它在Python文档中的使用示例包括 PyObject_HEAD 和 Py_BEGIN_ALLOW_THREADS 。

.. c:type:: name

描述C类型(无论是由 typedef 还是 struct 定义)。签名应该只是类型名称。

.. c:var:: declaration

描述全局C变量。签名应包括类型，例如:

.. c:var:: PyObject* PyClass_Type

交叉引用C构造

如果在文档中定义了以下角色，则会创建对C语言构造的交叉引用:

:c:func:

引用C语言函数。应该包括尾随括号。

:c:member:

引用结构的C语言成员。

:c:macro:

引用一个 “simple” 的C宏，如上所述。

:c:type:

引用C语言类型。

:c:data:

引用C语言变量。

C++ 域

C++ 域(名称 cpp)支持记录C++ 项目。

声明实体的指令

以下指令可用。所有声明都可以从可见性声明开始(public ，private 或 protected)

.. cpp:class:: class specifier
.. cpp:struct:: class specifier

描述一个类/结构，可能带有继承规范，例如:

.. cpp:class:: MyClass : public MyBase, MyOtherBase

区别 cpp:class 和 cpp:struct 只是装饰:输出中呈现的前缀，以及索引中显示的说明符。

该类可以直接在嵌套范围内声明，例如:

.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase

可以声明一个类模板:

.. cpp:class:: template<typename T, std::size_t N> std::array

或者换行:

.. cpp:class:: template<typename T, std::size_t N> \
               std::array

可以声明完整和部分模板特化:

.. cpp:class:: template<> \
               std::array<bool, 256>

.. cpp:class:: template<typename T> \
               std::array<T, 42>

2.0 新版功能: cpp:struct 指令。

.. cpp:function:: (member) function prototype

描述一个函数或成员函数，例如:

.. cpp:function:: bool myMethod(int arg1, std::string arg2)

   A function with parameters and types.

.. cpp:function:: bool myMethod(int, double)

   A function with unnamed parameters.

.. cpp:function:: const T &MyClass::operator[](std::size_t i) const

   An overload for the indexing operator.

.. cpp:function:: operator bool() const

   A casting operator.

.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept

   A constexpr function.

.. cpp:function:: MyClass::MyClass(const MyClass&) = default

   A copy constructor with default implementation.

函数模板也可以描述:

.. cpp:function:: template<typename U> \
                  void print(U &&u)

和函数模板专业化:

.. cpp:function:: template<> \
                  void print(int i)
.. cpp:member:: (member) variable declaration
.. cpp:var:: (member) variable declaration

描述变量或成员变量，例如:

.. cpp:member:: std::string MyClass::myMember

.. cpp:var:: std::string MyClass::myOtherMember[N][M]

.. cpp:member:: int a = 42

变量模板也可以描述:

.. cpp:member:: template<class T> \
                constexpr T pi = T(3.1415926535897932385)
.. cpp:type:: typedef declaration
.. cpp:type:: name
.. cpp:type:: type alias declaration

描述typedef声明中的类型，类型别名声明，或者只是具有未指定类型的类型的名称，例如:

.. cpp:type:: std::vector<int> MyList

   A typedef-like declaration of a type.

.. cpp:type:: MyContainer::const_iterator

   Declaration of a type alias with unspecified type.

.. cpp:type:: MyType = std::unordered_map<int, std::string>

   Declaration of a type alias.

类型别名也可以模板化:

.. cpp:type:: template<typename T> \
              MyContainer = std::vector<T>

该示例呈现如下。

typedef std::vector<int> MyList

类型的typedef式声明。

type MyContainer::const_iterator

声明具有未指定类型的类型别名。

using MyType = std::unordered_map<int, std::string>

声明类型别名。

template<typename T>
using MyContainer = std::vector<T>
.. cpp:enum:: unscoped enum declaration
.. cpp:enum-struct:: scoped enum declaration
.. cpp:enum-class:: scoped enum declaration

描述(范围)枚举，可能具有指定的基础类型。在unscoped枚举中声明的任何枚举器都将在枚举范围和父范围内声明。例子:

.. cpp:enum:: MyEnum

   An unscoped enum.

.. cpp:enum:: MySpecificEnum : long

   An unscoped enum with specified underlying type.

.. cpp:enum-class:: MyScopedEnum

   A scoped enum.

.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type

   A scoped enum with non-default visibility, and with a specified underlying type.
.. cpp:enumerator:: name
.. cpp:enumerator:: name = constant

描述一个枚举器，可选择定义其值，例如:

.. cpp:enumerator:: MyEnum::myEnumerator

.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
.. cpp:union:: name

描述一个联盟。

1.8 新版功能.

.. cpp:concept:: template-parameter-list name

警告

对概念的支持是实验性的。它基于当前的标准草案和概念技术规范。这些功能可能随着它们的发展而变化。

描述一个概念。它必须有1个模板参数列表。名称可以是嵌套名称。例:

.. cpp:concept:: template<typename It> std::Iterator

   Proxy to an element of a notional sequence that can be compared,
   indirected, or incremented.

   **Notation**

   .. cpp:var:: It r

      An lvalue.

   **Valid Expressions**

   - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
   - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable.

这将呈现如下:

template<typename It>
concept std::Iterator

代理到可以比较，间接或增量的有理序列的元素。

Notation

It r

一个左值。

Valid Expressions

  • *r, 当 r 是可解除引用的。

  • ++r ，返回类型 It&, when r 是可递增的。

1.5 新版功能.

选项

一些指令支持选项:

  • :noindex: , 看到 基本标记.

  • :tparam-line-spec: ，用于模板化声明。如果指定，则每个模板参数将在单独的行上呈现。

    1.6 新版功能.

匿名实体

C++ 支持匿名命名空间，类，枚举和联合。为了文档起见，必须给它们一些以 @ 开头的名字，例如 @42 或 @data 。这些名称也可用于交叉引用和(类型)表达式，但即使省略也会找到嵌套符号。 @ ... 名称将始终显示为 [anonymous] (可能作为链接)。

例:

.. cpp:class:: Data

   .. cpp:union:: @data

      .. cpp:var:: int a

      .. cpp:var:: double b

Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.

这将呈现为:

class Data
union [anonymous]
int a
double b

显式ref: Data::[anonymous]::a 。简写ref: Data::a 。

1.8 新版功能.

别名声明

有时，除了主要文档之外，它可能是有用的列表声明，例如，在创建类接口的概要时。以下指令可用于此目的。

.. cpp:alias:: name or function signature

插入一个或多个别名声明。可以在 cpp:any 角色中指定每个实体。如果给出了函数的名称(而不是完整的签名)，那么将列出函数的所有重载。

例如:

.. cpp:alias:: Data::a
               overload_example::C::f

becomes

int a
void f(double d) const
void f(double d)
void f(int i)
void f()

whereas:

.. cpp:alias:: void overload_example::C::f(double d) const
               void overload_example::C::f(double d)

becomes

void f(double d) const
void f(double d)

2.0 新版功能.

约束模板

警告

对概念的支持是实验性的。它基于当前的标准草案和概念技术规范。这些功能可能随着它们的发展而变化。

注解

Sphinx目前不支持 requires 条款。

占位符

声明可以使用概念的名称来引入受约束的模板参数，或者使用关键字“auto”来引入无约束的模板参数:

.. cpp:function:: void f(auto &&arg)

   A function template with a single unconstrained template parameter.

.. cpp:function:: void f(std::Iterator it)

   A function template with a single template parameter, constrained by the
   Iterator concept.

模板介绍

可以使用 template introduction 而不是模板参数列表声明简单约束函数或类模板:

.. cpp:function:: std::Iterator{It} void advance(It &it)

    A function template with a template parameter constrained to be an
    Iterator.

.. cpp:class:: std::LessThanComparable{T} MySortedContainer

    A class template with a template parameter constrained to be
    LessThanComparable.

它们呈现如下。

std::Iterator{It}
void advance(It &it)

具有模板参数的函数模板被约束为迭代器。

std::LessThanComparable{T}
class MySortedContainer

具有模板参数的类模板约束为 LessThanComparable。

但请注意，不会对参数兼容性进行检查。例如，Iterator{A，B，C} 将被接受作为介绍，即使它不是有效的 C++。

内联表达式和类型

:cpp:expr:
:cpp:texpr:

插入C++ 表达式或键入内联代码 (cpp:expr) 或内联文本 (cpp:texpr) 。例如:

.. cpp:var:: int a = 42

.. cpp:function:: int f(int i)

An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).

A type: :cpp:expr:`const MySortedContainer<int>&`
(or as text :cpp:texpr:`const MySortedContainer<int>&`).

将呈现如下:

int a = 42
int f(int i)

表达式: a * f(a) (或文本: a * f(a))。

类型: const MySortedContainer<int>& (或作为文本 const MySortedContainer<int>&)。

1.7 新版功能: cpp:expr 角色。

1.8 新版功能: cpp:texpr 角色。

命名空间

C++ 域中的声明默认放在全局范围内。可以使用三个命名空间指令更改当前范围。他们管理堆栈声明，其中 cpp:namespace 重置堆栈并更改给定的范围。“

cpp:namespace-push 指令将范围更改为当前范围的给定内部范围。

cpp:namespace-pop 指令撤消了最新的 cpp:namespace-push 指令。

.. cpp:namespace:: scope specification

将后续对象的当前范围更改为给定范围，并重置命名空间指令堆栈。请注意，命名空间不需要与C++ 命名空间相对应，但可以以类的名称结尾，例如:

.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass

将定义所有后续对象，就好像它们的名称是在前置范围的情况下声明的一样。将在当前范围中搜索后续交叉引用。

使用 NULL ， 0 或 nullptr 作为范围将变为全局范围。

命名空间声明也可以模板化，例如:

.. cpp:class:: template<typename T> \
               std::vector

.. cpp:namespace:: template<typename T> std::vector

.. cpp:function:: std::size_t size() const

将 size 声明为类模板 std :: vector 的成员函数。等价地，这可以使用:

.. cpp:class:: template<typename T> \
               std::vector

   .. cpp:function:: std::size_t size() const

要么:

.. cpp:class:: template<typename T> \
               std::vector
.. cpp:namespace-push:: scope specification

相对于当前范围更改范围。例如，之后:

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

the current scope will be A::B::C::D .

1.4 新版功能.

.. cpp:namespace-pop::

撤消之前的 cpp:namespace-push 指令(not 只是弹出作用域)。例如，之后:

.. cpp:namespace:: A::B

.. cpp:namespace-push:: C::D

.. cpp:namespace-pop::

当前范围将是 A :: B (not A::B::C)。

如果没有使用先前的 cpp:namespace-push 指令，但只使用 cpp:namespace 指令，则当前作用域将重置为全局作用域。也就是说，cpp:namespace :: A :: B 相当于:

.. cpp:namespace:: nullptr

.. cpp:namespace-push:: A::B

1.4 新版功能.

信息字段列表

C++ 指令支持以下信息字段(另请参阅 信息字段列表 ):

  • param, parameter, arg, argument: 参数说明。

  • tparam:模板参数的描述。

  • returns, return:返回值的描述。

  • throws, throw, exception: 可能抛出的异常的描述。

交叉引用

这些角色链接到给定的声明类型:

:cpp:any:
:cpp:class:
:cpp:struct:
:cpp:func:
:cpp:member:
:cpp:var:
:cpp:type:
:cpp:concept:
:cpp:enum:
:cpp:enumerator:

按名称引用C++ 声明(有关详细信息，请参见下文)。名称必须相对于链接的位置适当限定。

2.0 新版功能: cpp:struct 角色充当 cpp:class 角色的别名。

有关模板参数/参数的引用的注释

这些角色遵循Sphinx 交叉引用语法 规则。这意味着在引用(部分)模板专业化时必须小心，例如:如果链接看起来像这样: :cpp:class:`MyClass <int>` 。这被解释为 int 的链接，标题为 MyClass 。在这种情况下，用反斜杠转义开口尖括号，如下所示: :cpp:class:`MyClass\<int>` 。

当不需要自定义标题时，使用内联表达式的角色可能很有用 cpp:expr 和 cpp:texpr ，其中尖括号不需要转义。

没有模板参数和模板参数的声明

对于链接到非模板化声明，名称必须是嵌套名称，例如 f 或 MyClass::f 。

重载(成员)函数

当仅使用其名称引用(成员)函数时，引用将指向任意匹配的重载。 cpp:any 和 cpp:func roles 使用另一种格式，它只是一个完整的函数声明。这将解决完全匹配的重载。例如，请考虑以下类声明:

class C
void f(double d) const
void f(double d)
void f(int i)
void f()

引用使用 cpp:func 角色:

请注意 add_function_parentheses 配置变量不会影响特定的重载引用。

模板化的声明

假设以下声明。

class Wrapper
template<typename TOuter>
class Outer
template<typename TInner>
class Inner

通常，引用必须包含模板参数声明和限定名称前缀的模板参数。例如:

  • template\<typename TOuter> Wrapper::Outer (template<typename TOuter> Wrapper::Outer)

  • template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner (template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner)

目前，如果模板参数标识符是相等的字符串，则查找仅成功。也就是说，template\<typename UOuter> Wrapper :: Outer 将不起作用。

作为简写表示法，如果省略模板参数列表，则查找将采用主模板或非模板，而不是部分模板特化。这意味着以下参考资料也有效:“

(完整)模板专业化

假设以下声明。

template<typename TOuter>
class Outer
template<typename TInner>
class Inner
template<>
class Outer<int>
template<typename TInner>
class Inner
template<>
class Inner<bool>

通常，引用必须包含每个模板参数列表的模板参数列表。 因此可以参考上面的完整专业化 template\<> Outer\<int> (template<> Outer<int>) and template\<> template\<> Outer\<int>::Inner\<bool> (template<> template<> Outer<int>::Inner<bool>). 作为简写，可以省略空模板参数列表，例如， Outer\<int> (Outer<int>) and Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).

部分模板专业化

假设以下声明。

template<typename T>
class Outer<T *>

对部分特化的引用必须始终包含模板参数列表，例如 template\<typename T> Outer\<T *> (template<typename T> Outer< T *>)。目前，只有当模板参数标识符是相等的字符串时，查找才会成功。“

配置变量

请参阅 C++ 域选项 。

标准域

所谓的“标准”域收集所有不保证自己域名的标记。其指令和角色不以域名为前缀。

标准域也是使用 add_object_type() API添加的自定义对象描述的位置。“

有一组指令允许记录命令行程序:

.. option:: name args, name args, ...

描述命令行参数或开关。选项参数名称应括在尖括号中。例子:

.. option:: dest_dir

   Destination directory.

.. option:: -m <module>, --module <module>

   Run a module as a script.

该指令将为给定的选项创建交叉引用目标，可通过以下方式引用 option (在示例中，您将使用类似 :option:`dest_dir` , :option:`-m` , 要么 :option:`--module`)。

cmdoption 指令是 option 指令的弃用别名。

.. envvar:: name

描述文档化代码或程序使用或定义的环境变量。可引用者 envvar 。

.. program:: name

像 py:currentmodule ，这个指令不产生输出。相反，它用于通知Sphinx所有以下内容 option 指令文件选项称为 name 。

如果你使用 program ，你必须通过程序名来限定你的 option 角色中的引用，所以如果你有以下情况:

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r revision

   Specify the revision to work upon.

然后 :option:`rm -r` 将引用第一个选项，而 :option:`svn -r` 将引用第二个选项。

程序名称可能包含空格(如果你想分别记录 svn add 和 svn commit 这样的子命令)。

0.5 新版功能.

还有一个非常通用的对象描述指令，它不依赖于任何域:

.. describe:: text
.. object:: text

此伪指令生成与域提供的特定格式相同的格式，但不创建索引条目或交叉引用目标。例:

.. describe:: PAPER

   You can set this variable to select a paper size.

JavaScript域

JavaScript域(名称 js)提供以下指令:

.. js:module:: name

该指令设置后面的对象声明的模块名称。 模块名称用于全局模块索引和交叉引用中。 该指令不会创建如下的对象标题 py:class 。

默认情况下，此指令将创建一个可链接的实体，并将在全局模块索引中生成一个条目，除非指定了 noindex 选项。如果指定了此选项，则该指令将仅更新当前模块名称。

1.6 新版功能.

.. js:function:: name(signature)

描述JavaScript函数或方法。如果要将参数描述为可选，请使用方括号 documented 用于Python签名。

您可以使用字段来提供有关参数及其预期类型的​​更多详细信息，函数可能抛出的错误以及返回的值:

.. js:function:: $.getJSON(href, callback[, errback])

   :param string href: An URI to the location of the resource.
   :param callback: Gets called with the object.
   :param errback:
       Gets called in case the request fails. And a lot of other
       text so we need multiple lines.
   :throws SomeError: For whatever reason in that case.
   :returns: Something.

这表现为:

$.getJSON(href, callback[, errback])
参数

  • href (string) – 资源位置的URI。

  • callback – 使用对象调用。

  • errback – 在请求失败的情况下调用。还有很多其他文字，所以我们需要多行。

Throws SomeError

无论出于何种原因。

返回

某物.

.. js:method:: name(signature)

该指令是以下的别名 js:function ，但是它描述了一个作为类对象上的方法实现的函数。

1.6 新版功能.

.. js:class:: name

描述创建对象的构造函数。这基本上就像一个函数，但会出现一个 class 前缀:

.. js:class:: MyAnimal(name[, age])

   :param string name: The name of the animal
   :param number age: an optional age for the animal

这表现为:

class MyAnimal(name[, age])
参数

  • name (string) – 动物的名字

  • age (number) – 动物的选择年龄

.. js:data:: name

描述全局变量或常量。

.. js:attribute:: object.name

描述 object 的属性 name。

提供这些角色是为了引用所描述的对象:

:js:mod:
:js:func:
:js:meth:
:js:class:
:js:data:
:js:attr:

reStructuredText域

reStructuredText域(名称 rst)提供以下指令:

.. rst:directive:: name

描述reST指令。 name 可以是单个指令名称或实际指令语法(.. 前缀和 :: 后缀)，其参数将以不同方式呈现。例如:

.. rst:directive:: foo

   Foo description.

.. rst:directive:: .. bar:: baz

   Bar description.

将呈现为:

.. foo::

Foo描述。

.. bar:: baz

Bar 描述.

.. rst:role:: name

描述reST角色。例如:

.. rst:role:: foo

   Foo description.

将呈现为:

:foo:

Foo描述。

提供这些角色是为了引用所描述的对象:

:rst:dir:
:rst:role:

数学域

数学域(名称 math)提供以下角色:

.. rst:role:: math:numref

交叉引用方程的作用由以下定义 math 指令通过其标签定义。例:

.. math:: e^{i\pi} + 1 = 0
   :label: euler

Euler's identity, equation :math:numref:`euler`, was elected one of the
most beautiful mathematical formulas.

1.8 新版功能.

更多域

sphinx-contrib 存储库包含更多可用作扩展的域;目前有 Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP, 和 Ruby 域。另外还有 Chapel, Common Lisp, dqn, Go, Jinja, Operation, 和 Scala 的域。