关闭

测试Sphinx

662人阅读 评论(0) 收藏 举报

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.)
0
0

查看评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场
    个人资料
    • 访问:1722次
    • 积分:45
    • 等级:
    • 排名:千里之外
    • 原创:3篇
    • 转载:0篇
    • 译文:0篇
    • 评论:0条
    文章存档
    阅读排行