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

Python項(xiàng)目從1989年左右開始以來，文檔的寫作一直是使用LaTex。在80年代和90年代初，大多數(shù)的文檔都是被打印出來進(jìn)行學(xué)習(xí)，而不是在線進(jìn)行閱讀。LaTex被大范圍的使用是因?yàn)樗粌H提供了非常吸引人的打印效果，而且標(biāo)記規(guī)則學(xué)習(xí)起來也非常簡(jiǎn)單直接。

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

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

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

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

參考：

Documenting Python 描述了怎樣進(jìn)行Python文檔的寫作

Sphinx Sphinx的文檔和代碼.

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