sphinx 菜鳥教程
簡介
Sphinx 是一種工具，它允許開發人員以純文本格式編寫文檔，以便采用滿足不同需求的格式輕松生成輸出。這在使用 Version Control System 追蹤變更時非常有用。純文本文檔對不同系統之間的協作者也非常有用。純文本是當前可以采用的最便捷的格式之一。
雖然 Sphinx 是用 Python 編寫的，並且最初是為 Python 語言文檔而創建，但它並不一定是以語言為中心，在某些情況下，甚至不是以程序員為中心。Sphinx 有許多用處，比如可以用它來編寫整本書！
突出顯示
默認情況下，Sphinx 會為 Python 突出顯示代碼，但它還允許定義其他編程語言，比如 C 和 Ruby。
可以將 Sphinx 想像成為一種文檔框架：它會抽象化比較單調的部分，並提供自動函數來解決一些常見問題，比如突出顯示標題索引和特殊代碼（在顯示代碼示例時），以及突出顯示適當的語法。
參考python.org 官網 簡直不要太爽。
要求
您應該能輕車熟路地使用 Linux? 或 UNIX? 終端（也稱為控制臺或終端仿真器），因為命令行界面是與 Sphinx 進行互動的主要方式。
您需要安裝 Python。在所有主要的 Linux 發行版和一些基於 UNIX 的操作系統（如 Mac OSX）上預先安裝 Python 並做好使用它的準備。、
語法
Sphinx 使用 reStructuredText 標記語法（和其他一些語法）來提供文檔控制。如果您之前編寫過純文本文件，那麽您可能非常了解精通 Sphinx 所需的語法。
標記允許為適當的輸出實現文本的定義和結構。開始之前，請參見 清單 2 中的一個小的標記語法示例。
清單 2. Sphinx 標記語法示例
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
This is a Title
===============
That has a paragraph about a main subject and is set when the ‘=‘
is at least the same length of the title itself.
Subject Subtitle----------------
Subtitles are set with ‘-‘ and are required to have the same length
of the subtitle itself, just like titles.
Lists can be unnumbered like:
* Item Foo
* Item Bar
Or automatically numbered:
#. Item 1
#. Item 2
Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo``
gives you super user powers!
|
正如您所看到的，純文本格式的語法非常容易讀懂。在創建特定格式（如 HTML）時，標題會成為主要目標，其字體會比副標題大一些（理應如此），並且會對編號列表進行適當的編號。您已經擁有一些非常強大的功能。添加更多的項或更改編號列表中的順序不會影響到編號，而通過替換使用的下劃線可以改變標題的重要性。
安裝和配置
安裝是通過命令行進行的，非常簡單明了，如 清單 3 所示。
清單 3. 安裝 Sphinx
| 1 2 3 4 5 6 7 8 9 |
$ easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.0.5
Downloading http://pypi.python.org/packages/[...]
Processing Sphinx-1.0.5-py2.5.egg
[...]
Finished processing dependencies for sphinx
|
為了簡便起見，清單 3 中的內容有所縮減，但它提供了在一個在安裝 Sphinx 時應執行的操作的示例。
框架使用了一個目錄結構來分離源文件（純文本文件）和構建（指生成的輸出）。例如，如果使用 Sphinx 從文檔源中生成一個 PDF，那麽該文件會放置在構建目錄中。您可以更改此行為，但為了獲得一致性，我們還是保留了默認格式。
讓我們快速啟動 清單 4 的一個新的文檔項目，系統會通過一些問題提示您如何操作。請按下 Enter 鍵接受所有的默認值。
清單 4. 執行 sphinx-quickstart
| 1 2 3 4 5 6 |
$ sphinx-quickstart
Welcome to the Sphinx 1.0.5 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
[...]
|
我選擇 "My Project" 作為項目名稱，該名稱會在多處被引用。您可以隨意選擇不同的名稱。
運行 sphinx-quickstart 命令後，在工作目錄中會出現類似 清單 5 的文件。
清單 5. 工作目錄的列表
| 1 2 3 4 5 6 |
.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst
|
讓我們詳細研究一下每個文件。
- Makefile：編譯過代碼的開發人員應該非常熟悉這個文件，如果不熟悉，那麽可以將它看作是一個包含指令的文件，在使用
make命令時，可以使用這些指令來構建文檔輸出。 - _build：這是觸發特定輸出後用來存放所生成的文件的目錄。
- _static：所有不屬於源代碼（如圖像）一部分的文件均存放於此處，稍後會在構建目錄中將它們鏈接在一起。
- conf.py：這是一個 Python 文件，用於存放 Sphinx 的配置值，包括在終端執行
sphinx-quickstart時選中的那些值。 - index.rst：文檔項目的 root 目錄。如果將文檔劃分為其他文件，該目錄會連接這些文件。
入門指南
此時，我們已經正確安裝了 Sphinx，查看了默認結構，並了解了一些基本語法。不要直接開始編寫文檔。缺乏布局和輸出方面的知識會讓您產生混淆，可能耽誤您的整個進程。
現在來深入了解一下 index.rst 文件。它包含大量的信息和其他一些復雜的語法。為了更順利地完成任務並避免幹擾，我們將合並一個新文件，將它列在主要章節中。
在 index.rst 文件中的主標題之後，有一個內容清單，其中包括 toctree 聲明。toctree 是將所有文檔匯集到文檔中的中心元素。如果有其他文件存在，但沒有將它們列在此指令下，那麽在構建的時候，這些文件不會隨文檔一起生成。
我們想將一個新文件添加到文檔中，並打算將其命名為 example.rst。還需要將它列在 toctree 中，但要謹慎操作。文件名後面需要有一個間隔，這樣文件名清單才會有效，該文件不需要文件擴展名（在本例中為 .rst）。清單 6 顯示該列表的外觀。在文件名距離左邊距有三個空格的距離，maxdepth 選項後面有一個空白行。
清單 6. index.rst 中的 toctree 示例
| 1 2 3 4 5 6 |
Contents:
.. toctree::
:maxdepth: 2
example
|
此時，不用擔心其他選項。目前，註意到了有一個列出其他單獨的文件的索引文件，該文件可存儲有效文檔，因此，該列表有一定的順序和空格，才能使該列表變得有效。
還記得 清單 2 中的示例語法嗎? 請復制該示例，將它粘貼到 example.rst 文件中並保存它。現在我們準備生成輸出。
運行 make 命運，並將 HTML 指定為輸出格式。可直接將該輸出用作網站，因為它包含了生成的所有內容，包括 JavaScript 和 CSS 文件。請參見 清單 7。
清單 7. make html 命令的輸出
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.0.5
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
|
如果您對 make 命令提供的其他選項感興趣，請參見 清單 8，將幫助標誌傳至此處，並查看完整的描述。
清單 8. 列示 make 選項
| 1 2 3 4 |
$ make -h
Usage: make [options] [target] ...
Options:
[...]
|
生成靜態網站
隨著我們完成第一步操作，從兩個文件中生成 HTML 之後，我們就擁有一個完整的函數式（靜態）網站。
在 _build 目錄內，現在應該有兩個目錄：doctrees 和 HTML。我們對於這個存儲了文檔網站所需的全部文件的 HTML 目錄很感興趣。使用瀏覽器打開 index.html 文件，就會發現如 圖 1 所示的內容。
圖 1. 靜態 HTML 形式的主頁
雖然信息很少，但 Sphinx 能夠創建很多內容。我們擁有一個基本布局，該布局包含有關項目文檔、搜索部分、內容表、附帶名稱和日期的版權聲明、頁碼的一些信息。
搜索部分非常有趣，因為 Sphinx 已經為所有文件建立索引，並使用 JavaScript 的一些強大功能創建了一個可搜索的靜態網站。
還記得我們已將 example 作為一個單獨的文件添加至 清單 6 的 toctree 中的文檔嗎？您可以看到，主標題顯示為內容索引中的主要項目符號，副標題顯示為二級項目符號。Sphinx 小心維護著讓整個結構保持正確。
如果一開始就沒有成功...
進行一些修改後，只需再次運行 make 命令，即可生成這些文件。
所有的鏈接都指向文檔中的正確位置，並且標題和副標題均有定位點，允許直接進行鏈接。比如，Subject Subtitle 部分在瀏覽器中有一個類似 ../example.html#subject-subtitle 的定位點。如前所述，該工具消除了我們對這些瑣碎的、重復的需求的顧慮。
圖 2 顯示了 example.rst 如何顯示為靜態網站中的 HTML 文件。
圖2. HTML 頁面示例
添加圖形
簡明的段落、圖像和圖形都為項目文檔增加趣味性和可讀性。Sphinx 有助於利用這些有可能添加了靜態文件的主要元素來吸引讀者的註意。
添加靜態文件的正確語法很容易記憶。只要將靜態文件放置 _static 目錄（Sphinx 在創建文檔布局時創建了該目錄）中，就可以輕松地對其進行引用。在 清單 9，查看 reStructuredTex 文件中的引用應該是什麽樣子的。在本例中，我將其添加在 example.rst 的底部。
清單 9. example.rst 的靜態清單
| 1 |
.. image:: _static/system_activity.jpg
|
生成文檔之後，應將圖像正確放置在我們為有關系統活動的 JPEG 小圖像指定的地方。它看上起應該類似於 圖 3。
圖 3. 系統活動圖像
結束語
本文介紹了開始使用 Sphinx 的一些基礎知識，但仍有許多內容有待我們探索。Sphinx 能夠用不同的格式導出文檔，但要求安裝額外的庫和軟件。可生成的格式包括：PDF、epub、man (UNIX Manual Pages) 和 LaTeX。
對於復雜的圖形，有一個插件可將 Graphviz 圖形添加至您的文檔項目。我曾經不得不為一個小型辦公網絡地圖創建一個插件，但它表現相當出色，無需使用其他工具，便可在同一文檔中獲取所有的東西。與 Graphviz 插件類似，有大量可用於 Sphinx 的插件（亦稱為擴展）。Sphinx 提供了一些插件，比如 interSphinx，該插件允許您鏈接不同的 Sphinx 項目。
如果生成的輸出的外觀不符合您的喜好，Sphinx 還提供了許多主題，可應用它們來完全改變 HTML 文件呈現文檔的方式。一些重要的開源項目，如 Celery 和 Lettuce，通過更改 CSS 並擴展模板完全更改了 HTML 的外觀。請參閱 參考資料 部分，以獲取這些項目的鏈接、解釋如何擴展的文檔的鏈接以及修改默認 CSS 和布局的鏈接。
Sphinx 改變了我對編寫文檔的看法。從一開始的毫無靈感，到現在能夠輕易編制我的幾乎所有的個人開源項目以及少數內部項目，我感到非常興奮。使用 Sphinx 可輕松檢索遺忘在您自己文檔中的信息。
sphinx 菜鳥教程