用 Sphinx 寫文件

以下是最近試用 Sphinx 的心得, 有錯還請指正。

我原本很納悶, 專案文件是用 Wiki 寫好, 還是用 Sphinx 寫來得好。為啥要特別做個工具來產生文件呢? 抱著實驗的性質試了 Sphinx, 試下去才明白, 難怪不少專案用 Sphinx 來寫。

用 Sphinx 寫有幾個好處:

• 文件原始碼可和程式碼放在同一個 repository, 也可藉此順便做版本管理。不過我覺得以版本管理來說, 還是沒 Wiki 方便。
• 可透過語法載入程式碼內的註解, 這點 Wiki 就沒輒了, 我覺得這是用 Sphinx 的最大優勢。
• 一堆好用的 plugin, 像是畫圖、寫數學式子、畫 graph等。將 graphviz 原始碼直接寫在文件裡, 還挺方便的, 不過這點 Wiki 也辦得到。
• 可嵌入 ipython 語法, 顯示 ipython 的結果, 包含自動填入執行結果等功能。這個相當好用, 適合寫執行的範例 (寫實例演練的必備工具), Wiki 就沒有啦。
• 產生的結果是純 html, 並有提供文章搜尋功能 (實作方式很妙, 建好 index 存成 js 程式碼, 透過 js 執行搜尋)。架網站提供文件時, 不需另裝任合套件 (PHP / CGI / Web framework / etc)。
• 功能彈性, 若是 Python guy 的話, 缺什麼語法可自己寫 extension 補一下。Sphinx 也有提供巨集功能自定語法。

相較之下, Wiki 最大的好處是編完存檔就看到結果, 省掉 make html 的步驟, 方便大家隨時一起共筆, 提供 lock 避免多人同時編輯相衝, 方便查閱版次之間的差異。Sphinx 得透過 VCS 做, 也不方便提供 html 的版次差異。所以若是多人同時共筆, 偏重於功能說明, Wiki 還是較方便。

這裡列幾個熱門專案選擇的做法:

• 用 Sphinx: python、pip、virtualenv、Django、South
• Wiki: 除 Mercurial、Lucene、Hadoop 用 MoinMoinWikis (python 寫的 wiki), 另有不少專案的文件量不多, 會直接用 Google Code 或 github 提供的 Wiki 寫文件。

看完後發覺 ........, 一時好像也看不出個什麼頭緒, 之後再慢慢觀察吧。

Sphinx 入門不難, 以下是幾個相關網站:

• sampledoc: 一小份入門文件, 說明必要的部份, 快速上手。
• 線上試語法
• Read the Docs: Python Software Foundation 提供的網站, 設好後, 會自動 fetch codes, 並重編 Sphinx 文件, 還有支援顯示各個版本文件。有了這個站後, 就不用擔心用 Sphinx 還得自己另外找網站放文件。
• 官網: 東西多, 自然也較難找, 不過文件滿完整的

用 Sphinx 寫文件後, 我才明白文件包含兩種不同的內容: tutorial 和 library reference。像 Java Doc、Epydoc 這類工具用來抽註解產生 library reference, 避免在兩個地方寫文件。Java Doc 我沒實際試用, Epydoc 雖說產生的結果很炫, 卻不方便用作者自己的觀點組織整個專案的套件, 描述它們的互動, 或是提供常見的使用情境等。

使用者第一時間需要的是一個可立即執行的 tutorial, library reference 則是備查。Sphinx 好用的地方就在於, 它可以自由組織 tutorial, 並提供語法引入 library reference (用 autodoc 或 Epydoc extension )。所以用 Sphinx 可同時滿足這兩種需求。

除 tutorial 和 library reference, 開發者可能會需要 system context 和 architecture overview 了解整個架構。這部份就得自己另外用工具畫, Power Point 之類的軟體滿適合的, 重點是容易上手。最近看了《How to make Awesome Diagrams for your slides》 覺得相當有幫助, 順便列在這備忘。