新的文檔格式：使用reStructuredText的Sphinx

Python項目從1989年左右開始以來，文檔的寫作一直是使用LaTex。在80年代和90年代初，大多數(shù)的文檔都是被打印出來進行學習，而不是在線進行閱讀。LaTex被大范圍的使用是因為它不僅提供了非常吸引人的打印效果，而且標記規(guī)則學習起來也非常簡單直接。

現(xiàn)在，LaTex仍然被用于寫作需要出版的作品，但是在編程工具領(lǐng)域，情況以及發(fā)生改變。我們不再打印大量的文檔，相反，我們開始在線閱讀，并且 HTML已經(jīng)成為了需要支持的最重要的一種格式。遺憾的是，從LaTex轉(zhuǎn)換到HTML比較復(fù)雜，而且Fred L. Drake Jr.，長期的Python文檔編輯，已經(jīng)花費了大量的時間來維護文檔轉(zhuǎn)換的流程。不時會有人建議將文檔轉(zhuǎn)換成SGML以及后來的XML格式，但是始終沒有人能夠拿出足夠的時間來完成主要的轉(zhuǎn)換工作。

在2.6的開發(fā)周期中，Georg Brandl花費了大量的精力，為文檔處理創(chuàng)建了一個新的工具鏈(toolchain)，就是Sphinx，在http://sphinx./可以找到。

Sphinx致力于HTML輸出，產(chǎn)生有吸引力，時髦的HTML；打印輸出仍然可以通過轉(zhuǎn)換成LaTex來搞定。文檔的輸入格式是reStructuredText，一種支持自定義擴展和指令，在Python社區(qū)經(jīng)常被使用的標記語言。

Sphinx是一個可以用于寫作的獨立的package，已經(jīng)有將近20多個其他的項目（參見Sphinx的網(wǎng)站 ）已經(jīng)將Sphinx作為他們的文檔工具。

參考：

Documenting Python 描述了怎樣進行Python文檔的寫作

Sphinx Sphinx的文檔和代碼.

Docutils 底層的reStructuredText解析器和工具集