5. API 文档和生成内容 

5.1. `test_py_module`

sphinx_rtd_theme 的测试模块。

class test_py_module.test.Foo(qux, spam=False)[source]

Foo 类的文档字符串。

此文本测试从 sphinx.ext.autodoc 输出生成的文档字符串的格式。其中包含 reST，但 sphinx 将其嵌套在 <dl> 和 <dt> 标签中。此外，<tt> 用于类、方法名称等，但这些始终具有 .descname 或 .descclassname 类。

术语: 也可以在文档字符串中包含定义。它们应该像普通定义列表一样进行样式设置。

字段列表:: 也可以在文档字符串中包含定义。它们应该像普通定义列表一样进行样式设置。

[引用]

引用包含主体元素，一致地缩进至少 3 个空格。

普通 <tt>（就像我在这里编写的 <tt>）需要以与任何其他使用 ``this type of markup`` 的内容相同的样式显示。

程序员通常会在文档字符串中提供代码示例

from test_py_module import Foo

myclass = Foo()
myclass.dothismethod('with this argument')
myclass.flush()

print(myclass)

这是一个到 capitalize() 的链接。这是一个到 __init__() 的链接。

__init__(qux, spam=False)[source]

启动 Foo。

参数:

qux (string) – 初始化类的第一个参数。
spam (bool) – 给我发送垃圾邮件是或否…

__weakref__: 对象（如果定义）的弱引用列表

add(val1, val2)[source]

返回相加的值。

参数:

val1 (int) – 要添加的第一个数字。
val2 (int) – 要添加的第二个数字。

返回类型:

int

此方法的参数在参数列表中描述。

another_function(a, b, **kwargs)[source]

这是另一个函数。

参数:

a (int) – 你拥有的绿色帽子的数量。
b (int) – 你拥有的非绿色帽子的数量。
kwargs (float) – 其他关键字参数。每个关键字参数应指定您最喜欢的菜系的名称。值应为浮点数，指定您在该烹饪风格中最喜欢的菜肴的平均价格。

返回:

一个 2 元组。第一个元素是跨菜系所有菜肴的平均价格。第二个元素是您拥有的帽子总数： \(a + b\)。

返回类型:

tuple

引发:

ValueError – 当 a 不是整数时。

版本 1.0 中的新增功能：这在 1.0 中添加。

版本 2.0 中的更改：这在 2.0 中更改。

自版本 3.0 起弃用：自 3.0 起弃用。

bar = 1: Foo.bar 类属性的文档注释。它可以有多行。

baz = 2: Foo.baz 类属性的文档字符串。

capitalize(myvalue)[source]

将字符串作为大写返回。

参数:: myvalue (string) – 要更改的字符串
返回类型:: string

flox = 1.5: Foo.flox 的文档注释。仅一行。

qux: 实例属性 qux 的文档注释。

spam: 实例属性 spam 的文档字符串。

test_py_module.test.add_numbers(a: int, b: int = 0) → int[source]

将两个数字加在一起

参数:

a – 第一个数字
b – 第二个数字

这是一些更多文本。

test_py_module.test.subtract_numbers(a: int, b: int = 0) → int[source]

减去两个数字

参数:

a – 第一个数字
b – 第二个数字

5.2. C++ API 

type MyType

某种类型

const MyType Foo(const MyType bar): 某些函数类型的东西

template<typename T, std::size_t N> class std::array: 一些cpp类

float Sphinx::version: Sphinx::version 的描述。

int version: version 的描述。

typedef std::vector<int> List: List 类型的描述。

enum MyEnum

一个未限定作用域的枚举。

enumerator A

enum class MyScopedEnum

一个限定作用域的枚举。

enumerator B

protected enum struct MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type

一个具有非默认可见性和指定底层类型的限定作用域枚举。

enumerator B

5.3. JavaScript API 

链接到 ModTopLevel()

class module_a.submodule.ModTopLevel()

链接到 mod_child_1()
链接到 ModTopLevel.mod_child_1()

ModTopLevel.mod_child_1()

链接到 mod_child_2()

ModTopLevel.mod_child_2()

链接到 module_a.submodule.ModTopLevel.mod_child_1()

链接到 ModTopLevel()

class module_b.submodule.ModNested()

ModNested.nested_child_1()

链接到 nested_child_2()

ModNested.nested_child_2()

链接到 nested_child_1()

5.4. 生成的索引 

Sphinx 构建过程的一部分是生成索引文件：索引。

5.5. 可选参数 args 

此时，可选参数无法从代码生成。但是，某些项目会手动执行此操作，如下所示

此示例来自django-payments 模块文档。

class payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl'])

此后端使用流行的波兰支付网关 Dotpay.pl 实现支付。

由于 API 限制，不支持转移已购买的商品。

参数:

seller_id – Dotpay 分配的卖家 ID
pin – Dotpay 分配的 PIN 码
channel – 默认支付渠道（请参阅参考指南）
lang – UI 语言
lock – 是否禁用上面选择的默认渠道以外的其他渠道

5.6. 数据 

test_py_module.test.Data_item_1
test_py_module.test.Data_item_2
test_py_module.test.Data_item_3: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis。

一些数据链接 Data_item_1。

5.7. Sphinx 扩展 

5.7.1. sphinx.ext.autosummary 

`test_py_module.test.add_numbers`(a[, b])	将两个数字加在一起
`test_py_module.test.subtract_numbers`(a[, b])	减去两个数字
`test_py_module.test.Foo`(qux[, spam])	Foo 类的文档字符串。