chap 02 First Steps with Sphinx
這篇文檔意味著給你一個類教程的預覽，此處的標注是說要更深入的研究。
2.1 設置文檔源
一個文檔集的根目錄，被稱為 源目錄 。這個目錄包含了Sphinx的配置文件 conf.py ，在這里，你可以配置各個方面，讓Sphinx讀取你的源和建造你的文檔。
Sphinx用一個腳本來設置源目錄，創建 conf.py ，只要運行：
然后回答它的問題。（確保都回答了。）
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那么會告訴你，哪些是可用的。
2.5 文檔對象
Sphinx的主要目標之一，就是簡化在任何 domain的 object 。一個 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.)