七月 30, 2008
» 試玩 Sphinx 之 3

試玩完前兩部之後,還是不了解 Sphinx 的話,
直接來看個 Screencast (視頻演示)吧

三月 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 資料的資料夾. 語法備忘 ==

biggo.com.tw

A Django site.