» 試玩 Sphinx 之 3
試玩完前兩部之後，還是不了解 Sphinx 的話，
直接來看個 Screencast (視頻演示)吧
七月 30, 2008
三月 26, 2008
» 試玩 Sphinx 之 2
之前提到過 Python 2.6 新採用了一套叫做 Sphinx 的 rst 文件生成系統來管理 Python 語言官方的文件資料，用 sphinx 所生成的文件網站除了頁面能自訂樣式，自訂文件導覽順序，甚至還有附有搜尋功能。
已經寫過一篇 試玩 Sphinx。
而現在值得再提的是，Sphinx 專案已經獨立出來了，可以將 sphinx 應用在任何需要文件網站的情況裡。
1. 安裝
easy_install sphinx
2. 打開命令列，找個目錄，鍵入
sphinx-quickstart
照著互動提示輸入一些生成訊息後， sphinx 會在目錄中生成幾個簡單的檔案。
目錄中生成幾個簡單的檔案其內容為：
* conf.py
conf.py 中的內容大部分是我們剛剛在互動提示中填入的資訊，在此都可以修改。
* MAKEFILE
給 linux 或 mac 用的 make 檔。
* index.rst
index.rst 等於是整個文件站台的主頁
* .template
文件站台的樣板，要自訂樣板就修改這。
* .static
靜態文件，如圖片等內容。
* .build
建立(編譯)好的文件在此。
.template/.static/.build 這樣的檔案在 windows 下不易辨識，可以在互動提示中詢問 "Name prefix for templates and static dir [.]:" 時，將 '.' 改成 '_'。 那麼生成的資料夾就會變成 _template/_static/_build。
3. 建立文件
sphinx 會在目錄中生成 make 檔，輸入
make html
即能產生完整的 html 文件站台。
如此一來，整個完整的站台都能用 rst 格式來構成啦，實在便利。
沒有寫過 rst (結構化)文件的人，也可以參考 reStructuredText Primer。
PS: 順帶一提， Pylons 與 TurboGears2 都已經有 sphinx 支持了。 TurboGears2 的部份(這個是我加進去的)可以用原始碼 docs 目錄中的 get_tgdoc.py 從 docs.turbogears.org 自動下載 rst 格式文件，然後再用上面提到的 'make html' 轉成 html 文件檔。
» 試玩 Sphinx
Sphinx 是 Python 2.6 新採用的 rst 文件生成系統.
要開始玩首先得下載 Python 原始碼
svn co http://svn.python.org/projects/doctools/trunk/ python
下載完後進入 Doc 目錄, 輸入
make html
則會自動下載 sphinx 與相關程式, 然後自動編譯 rst 檔案.
如果輸入
make web
的話則是產生一個可執行的線上網頁文件程式. 此網站程式甚至還支援搜尋, 真是強悍到有點扯 @@
Update:
Sphinx 產生的首頁原來是從 template 中 render 的. 看來拿到其他地方重用的彈性並沒想像中的高.
一般使用 rst 時還是繼續用自己寫的 mopowg 吧.
三月 17, 2007
» 結構文本(rst)轉網頁投影片(s5)
在看 pycon-trac-presentation 時, 發現 Matt Good 用 docutils 模組提供的"rst2s5" 套件來將結構文本(rst) 轉換成網頁投影片(s5) 效果還蠻不錯的. 用他客製化的 rst2s5 模組可以透過 pygments 支援程式的語法高亮展示. 以下提供使用方法 下載 ==== $ easy_install docutils $ easy_install docutils pygments 並下載 rst2s5 with code high lighting 用法 ==== rst2s5.py [輸入].rst [輸出].html i.e. rst2s5.py xxx.rst ooo.html 會產生的輸出結果是 "ooo.html" 這個檔名的檔案, 跟一個包含 s5 投影片 js/css 資料的資料夾. 語法備忘 ==
