Skip to main content

4 posts tagged with "rst"

View All Tags

· 3 min read

之前提到過 Python 2.6 新採用了一套叫做 Sphinx 的 rst 文件生成系統來管理 Python 語言官方的文件資料，用 sphinx 所生成的文件網站除了頁面能自訂樣式，自訂文件導覽順序，甚至還有附有搜尋功能。

已經寫過一篇 試玩 Sphinx。

而現在值得再提的是，Sphinx 專案已經獨立出來了，可以將 sphinx 應用在任何需要文件網站的情況裡。

1. 安裝

easy_install sphinx

2. 打開命令列，找個目錄，鍵入

sphinx-quickstart

照著互動提示輸入一些生成訊息後， sphinx 會在目錄中生成幾個簡單的檔案。

目錄中生成幾個簡單的檔案其內容為：

  • conf.py

conf.py 中的內容大部分是我們剛剛在互動提示中填入的資訊，在此都可以修改。

0.5 版之後支援中文介面 (我丟的 Patch)，只要在 conf.py 中指定「language = 'zh_TW'」即可。

  • 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 文件檔。

· One min read

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 吧.

· 2 min read

在看 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 資料的資料夾.

語法備忘

=======
標題
=======

:Author: Fred Lin
:Date:   $Date: 2007-03-16 $

一張投影片
==========

.. code-block:: pycon

  >>> # python console

.. class:: handout

   handout 是放註解的地方. 不會 show 到投影片上
   code-block 可用 pygments 提供的各種語法高亮, 如 pycon, python, bash, html...

投影片再一張
============

.. class:: incremental

   * 1st. item
   * 2nd. item

.. image:: python.png

.. class:: handout

   依序顯示重點. image 會嵌入圖片.

.. include:: pylevels.rst

語法參考
========

http://docutils.sourceforge.net/docs/user/slide-shows.html

.. class:: handout

   前一張後的 include 語句支援嵌套其他 rst 文件.