chap 02 First Steps with Sphinx
這篇文檔意味著給你一個(gè)類(lèi)教程的預(yù)覽，此處的標(biāo)注是說(shuō)要更深入的研究。
2.1 設(shè)置文檔源
一個(gè)文檔集的根目錄，被稱(chēng)為 源目錄 。這個(gè)目錄包含了Sphinx的配置文件 conf.py ，在這里，你可以配置各個(gè)方面，讓Sphinx讀取你的源和建造你的文檔。
Sphinx用一個(gè)腳本來(lái)設(shè)置源目錄，創(chuàng)建 conf.py ，只要運(yùn)行：
然后回答它的問(wèn)題。（確保都回答了。）
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í)是空的，它看起來(lái)像這樣：
.. toctree::
:maxdepth: 2
你需要增加文檔的列表：
.. toctree::
:maxdepth: 2
intro
tutorial
...
這就是toctree看起來(lái)的樣子。這個(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”來(lái)察看源代碼。
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)用：
然后就會(huì)創(chuàng)建目標(biāo)文件。如果沒(méi)有參數(shù)執(zhí)行make那么會(huì)告訴你，哪些是可用的。
2.5 文檔對(duì)象
Sphinx的主要目標(biāo)之一，就是簡(jiǎn)化在任何 domain的 object 。一個(gè) domain 就是對(duì)象類(lèi)型的集合，擁有創(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ì)看起來(lái)像這樣：
- 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.)