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 可輕鬆檢索遺忘在您本身文檔中的信息。