2.1 設(shè)置文檔源¶

一個(gè)文檔集的根目錄，被稱為 源目錄 。這個(gè)目錄包含了Sphinx的配置文件 conf.py ，在這里，你可以配置各個(gè)方面，讓Sphinx讀取你的源和建造你的文檔。

Sphinx用一個(gè)腳本來設(shè)置源目錄，創(chuàng)建 conf.py ，只要運(yùn)行：

$ sphinx-quickstart

然后回答它的問題。（確保都回答了。）

2.2 定義文檔結(jié)構(gòu)¶

首先假設(shè)你已經(jīng)運(yùn)行了Sphinx-quickstart 。它創(chuàng)建了一個(gè)源目錄，包括 conf.py和一份主文檔， index.rst（如果你接受默認(rèn)值）。主文檔的主要功能是提供一個(gè)歡迎界面，包含一個(gè)目錄，（“table of contents tree”或 toctree）。這就是主要的一件事，把多個(gè)文件組織在一起。

reStructuredText directives
toctree是reStructuredText的指令，
是很多標(biāo)記中的一種。
指令可以有參數(shù)，選項(xiàng)和內(nèi)容。
參數(shù)，在兩個(gè)冒號(hào)之后。
每個(gè)指令決定了它是否有參數(shù)，
有幾個(gè)。
選項(xiàng)，在參數(shù)之后，
是一個(gè)列表。
內(nèi)容緊跟在選項(xiàng)或參數(shù)的空白行之后，
每個(gè)指令決定了是否允許接內(nèi)容。
內(nèi)容需要縮減。

toctree指令初始化時(shí)是空的，它看起來像這樣：

.. toctree::
:maxdepth: 2

你需要增加文檔的列表：

.. toctree::
:maxdepth: 2
intro
tutorial
...

這就是toctree看起來的樣子。這個(gè)文檔要包括的，是給定文檔的名字，但不要文檔的后綴，然后使用斜杠作為目錄分割符。

你可以現(xiàn)在就創(chuàng)建文件，把他們添加到toctree中，他們的章節(jié)都會(huì)被插入。Sphinx會(huì)知道你的文檔的結(jié)構(gòu)和順序。（而他們內(nèi)部又可以包含toctree，這就意味著，你可以創(chuàng)建更復(fù)雜的層次結(jié)構(gòu)。）

2.3 增加內(nèi)容¶

在Sphinx源文件中，你可以使用很多reStructuredText的標(biāo)準(zhǔn)特性。當(dāng)然，也有Sphinx增加的。舉個(gè)例子，你可以增加交叉引用，使用 ref 。

舉個(gè)例子，如果你正在觀察HTML版本，你可以點(diǎn)擊側(cè)邊欄上的“Show Source”來察看源代碼。

2.4 運(yùn)行創(chuàng)建¶

現(xiàn)在，你已經(jīng)增加一些文件和目錄，讓我們第一次創(chuàng)建這個(gè)文檔。創(chuàng)建時(shí)運(yùn)行：

$ sphinx-build -b html sourcedir builddir

此處， sourcedir是源目錄，而 builddir 是你要存放創(chuàng)建文檔的地方。

選項(xiàng) -b 選擇了一個(gè)builder，此處就是創(chuàng)建HTML文件。

但是， sphinx-quickstart創(chuàng)建了一個(gè)makefile和make.bat，然后你就可以這樣調(diào)用：

$ make html

然后就會(huì)創(chuàng)建目標(biāo)文件。如果沒有參數(shù)執(zhí)行make那么會(huì)告訴你，哪些是可用的。

2.5 文檔對(duì)象¶

Sphinx的主要目標(biāo)之一，就是簡化在任何 domain的 object 。一個(gè) domain 就是對(duì)象類型的集合，擁有創(chuàng)建和引用各個(gè)對(duì)象的標(biāo)記。

其中最重要的 domain ，要屬Python。為了舉個(gè)python內(nèi)置函數(shù) enumerate的例子，你會(huì)把下面這段添加進(jìn)去：

.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index
and an item of the *sequence*. (And so on.)

他會(huì)看起來像這樣：

enumerate(sequence[, start=0])¶

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

這個(gè)指令的參數(shù)是這個(gè)你要描述對(duì)象的簽名，而內(nèi)容則是對(duì)他的描述。對(duì)于多個(gè)簽名，可以每行放一個(gè)。

Python是默認(rèn)的 domain ，所以呢，你可以不用放這個(gè)前綴，就可以表示它了：

.. function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index
and an item of the *sequence*. (And so on.)