测试Sphinx

这篇教程介绍了如何使用Sphinx创建和管理文档,包括设置源目录、定义文档结构、添加内容、运行构建过程,以及如何处理文档对象,特别是Python域的对象。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

chap 02 First Steps with Sphinx

这篇文档意味着给你一个类教程的预览,此处的标注是说要更深入的研究。

2.1 设置文档源

一个文档集的根目录,被称为 源目录 。这个目录包含了Sphinx的配置文件 conf.py ,在这里,你可以配置各个方面,让Sphinx读取你的源和建造你的文档。

Sphinx用一个脚本来设置源目录,创建 conf.py ,只要运行:

$ sphinx-quickstart

然后回答它的问题。(确保都回答了。)

2.2 定义文档结构

首先假设你已经运行了Sphinx-quickstart 。它创建了一个源目录,包括 conf.py和一份主文档, index.rst(如果你接受默认值)。主文档的主要功能是提供一个欢迎界面,包含一个目录,(“table of contents tree”或 toctree)。这就是主要的一件事,把多个文件组织在一起。

reStructuredText directives

toctree是reStructuredText的指令,
是很多标记中的一种。
指令可以有参数,选项和内容。

参数,在两个冒号之后。
每个指令决定了它是否有参数,
有几个。

选项,在参数之后,
是一个列表。

内容紧跟在选项或参数的空白行之后,
每个指令决定了是否允许接内容。

内容需要缩减。

toctree指令初始化时是空的,它看起来像这样:

.. toctree::
    :maxdepth: 2

你需要增加文档的列表:

.. toctree::
    :maxdepth: 2

    intro
    tutorial
    ...

这就是toctree看起来的样子。这个文档要包括的,是给定文档的名字,但不要文档的后缀,然后使用斜杠作为目录分割符。

你可以现在就创建文件,把他们添加到toctree中,他们的章节都会被插入。Sphinx会知道你的文档的结构和顺序。(而他们内部又可以包含toctree,这就意味着,你可以创建更复杂的层次结构。)

2.3 增加内容

在Sphinx源文件中,你可以使用很多reStructuredText的标准特性。当然,也有Sphinx增加的。举个例子,你可以增加交叉引用,使用 ref

举个例子,如果你正在观察HTML版本,你可以点击侧边栏上的“Show Source”来察看源代码。

2.4 运行创建

现在,你已经增加一些文件和目录,让我们第一次创建这个文档。创建时运行:

$ sphinx-build -b html sourcedir builddir

此处, sourcedir是源目录,而 builddir 是你要存放创建文档的地方。

选项 -b 选择了一个builder,此处就是创建HTML文件。

但是, sphinx-quickstart创建了一个makefile和make.bat,然后你就可以这样调用:

$ make html

然后就会创建目标文件。如果没有参数执行make那么会告诉你,哪些是可用的。

2.5 文档对象

Sphinx的主要目标之一,就是简化在任何 domainobject 。一个 domain 就是对象类型的集合,拥有创建和引用各个对象的标记。

其中最重要的 domain ,要属Python。为了举个python内置函数 enumerate的例子,你会把下面这段添加进去:

.. py:function:: enumerate(sequence[, start=0])

    Return an iterator that yields tuples of an index
    and an item of the *sequence*. (And so on.)

他会看起来像这样:

enumerate ( sequence [, start=0 ] )

Return an iterator that yields tuples of an indexand an item of the sequence. (And so on.)

这个指令的参数是这个你要描述对象的签名,而内容则是对他的描述。对于多个签名,可以每行放一个。

Python是默认的 domain ,所以呢,你可以不用放这个前缀,就可以表示它了:

.. function:: enumerate(sequence[, start=0])

    Return an iterator that yields tuples of an index
    and an item of the *sequence*. (And so on.)
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值