用sphinx寫文檔

1 Sphinx簡介

Sphinx是一個開源的文檔工具。最開始被設計用于建立新的Python文檔，後來被廣泛應用與Python項目，現在對C／C++的支援也已經相當不錯。并且正在逐漸增加對更多其他程式設計語言的支援。Sphinx有以下主要功能：

1，支援多種輸出格式，HTML，LaTeX, ePub, Texinfo, manual pages, plain text

2，支援大量交叉引用，文法标記，函數、類，引用、術語等類似資訊的自動連結；

3，支援文檔層次結構，通過兄弟，父親孩子節點間的自動連結實作輕松定義文檔樹形結構；

4，自動索引；

5，代碼高亮處理

6，更多的擴充支援

Sphinx使用reStructuredText做為文檔标記語言。很多開源項目都使用Sphinx寫官方文檔，在日常的工作，學習、生活中，我們不僅可以用Sphinx寫項目文檔，還可以利用reStructuredText所見及所得特性，以及Sphinx其他友善的功能寫部落格，記筆記等。

2 安裝和配置

2.1 安裝

Sphinx的安裝可以使用源碼包，esay-insall和PyPI等多種方式。

$ sudo pip install Sphinx
           

2.2 快速配置

Sphinx提供了一個互動式的快速配置指令sphinx-quickstart。執行sphinx-quickstart，并根據提示指定工程目錄，及配制。

$ sphinx-quickstart
           

最後sphinx-quickstart會在指定的工程目錄下自動生成y一些檔案及檔案夾。執行過程中，輸入的配置項不同，生成的目錄層次結構可能不同。但主要會有以下幾個檔案或檔案夾。 1，build 檔案夾，用于存放生成的目标我檔案的目錄 2，Makefile，執行make指令生成相應格式的目标檔案 3，conf.py，配置檔案，内容為執行shpinx-quickstart選擇的配置内容 4，_static目錄，所有不屬于源代碼的檔案，如圖像等都放在這個目錄中 5，index.rst，文檔項目的根目錄，如果有其他文檔檔案，此檔案用于自動連結組織其他檔案。（注：index可在配置時指定是否使用其他名字，預設為index）

</pre><pre name="code" class="plain">.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── _static
    ├── _templates
    └── index.rst
           

3, 編輯文檔

Sphinx使用reStructuredText作為文檔标記語言，文法簡單，所見即所得。如果在執行sphinx-quickstart時使用預設的index.rst做為項目根目錄，則項目根目錄下的index.rst将是整個項目文檔的入口檔案。在index.rst中根據reStructuredText文法編輯文檔，最後就可以通過Makefile編譯出各種格式的文檔。 由于reST并沒有多文檔互相連結引用的機制，或者使用多個源檔案編譯文檔。Sphinx使用使用者定制的指令增加了可以将多個源檔案互相連結形成最終文檔的機制。toctree(Table of Content Tree) 就是這種機制的核心組成。

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   usr/index
   (many more documents listed here)
           

maxdepth表示最大的嵌入是層級，2表示還可以再嵌入一層父層級結構。子層級中的toctree也應當要計算在内。需要引用的源文檔，直接列在toctree目錄中即可，Sphinx預設使用".rst"擴充名的文檔，是以不用指定字尾名。如果源檔案在其他目錄中，需要指定路徑。

自動生成的配置檔案“conf.py"是一個python源檔案，如果需要更改配置，可以直接修改配置檔案，而不用重新執行sphinx-quickstart。同時如果在文檔中需要引用某些在配置檔案中定義的變量，可以直接使用reST的引用格式引用該變量，引用後編譯文檔時會進行自動替換。

4，編譯

Sphinx安裝後支援多種格式的輸出，如html，latex，epub等。檢查Makefile及可知道預設支援的編譯格式。但是如果想要直接編譯成pdf則需要安裝python rst2pdf子產品，還需要修改conf.py和Makefile。或者先編譯成latex格式，然後再轉換成pdf格式，同樣也需要pdflatex的支援。 直接執行make指令即可得到相應格式的輸出：

$ make html
           

$ make latex
           

編譯完成後，相應的輸出文檔将在_build目錄下生成。

5， 總結

工作中，python相關的項目技術文檔使用Sphinx完成，實際使用中給項目帶來相當大的便利。生成的HTML文檔可以友善的轉換成confluence頁面，也可以友善的生成PDF文檔，省去了很多不同格式間轉換的麻煩。同時reST簡單的格式，可以讓開發者将更多的精力放在文檔正文上，而不用過多的糾結文檔編排。 由于日常工作中主要接觸的是英文文檔，還沒有嘗試過用Sphinx寫中文文檔，聽說如果需要支援中文格式，還需要額外的配置。下一篇Blog将嘗試用Sphinx寫，同時研究下Sphinx的中文支援。 Stay tune！

參考資料

1. Sphinx Overview： http://sphinx-doc.org/
2. First steps with Sphinx：http://sphinx-doc.org/tutorial.html
3. reStructuredText入門：http://sphinx-doc-zh.readthedocs.org/en/latest/rest.html
4. reStructuredText簡明教程： http://jwch.sdut.edu.cn/book/rst.html
5. Quick reStructuredText : http://docutils.sourceforge.net/docs/user/rst/quickref.html