先看看網頁在leo中的組織形式：
詳細內容：
網頁後請看：
http://leoeditor.com/tutorial-rst3.html
###########################################################################
現在開始講解rst和sphinx
1：rst和sphinx是什麼關係？
Sphinx 是一種文檔工具，它可以令人輕鬆的撰寫出清晰且優美的文檔, 由 Georg Brandl 在BSD 許可證下開發. 新版的Python文檔 就是由Sphinx生成的， 並且它已成爲Python項目首選的文檔工具,同時它對 C/C++ 項目也有很好的支持; 並計劃對其它開發語言添加特殊支持. 本站當然也是使用 Sphinx 生成的，它採用reStructuredText! Sphinx還在繼續開發. 下面列出了其良好特性,這些特性在Python官方文檔中均有體現:
- 豐富的輸出格式: 支持 HTML (包括 Windows 幫助文檔), LaTeX (可以打印PDF版本), manual pages（man 文檔）, 純文本
- 完備的交叉引用: 語義化的標籤,並可以自動化鏈接函數,類,引文,術語及相似的片段信息
- 明晰的分層結構: 可以輕鬆的定義文檔樹,並自動化鏈接同級/父級/下級文章
- 美觀的自動索引: 可自動生成美觀的模塊索引
- 精確的語法高亮: 基於 Pygments 自動生成語法高亮
- 開放的擴展: 支持代碼塊的自動測試,幷包含Python模塊的自述文檔(API docs)等
Sphinx 使用 reStructuredText 作爲標記語言, 可以享有 Docutils 爲reStructuredText提供的分析，轉換等多種工具.
Leo’s rst3 command converts Leo trees containing reStructuredText (rST) or Sphinx markup to HTML, PDF, LaTeX and other kinds of output files. This tutorial gives step-by-step instructions for using the rst3 command.
Prerequisites: Please make sure you have read the first tutorial before reading this one. If you are new to rST, please read the rST primer. For full information about Sphinx, please read the Sphinx documentation.
2：安裝
The rst3 command requires the docutils Python package. You must also install the Sphinx package if you use sphinx markup. Sphinx gives Leo’s and Python’s web sites their distinctive appearance and features.
After installing docutils or sphinx, you must restart Leo so that the new installation will take effect.
安裝python-docutils
-
通過發行版的包管理器直接安裝:
sudo apt-get install python-docutils sudo apt-get install rst2pdf
-
通過Python pip來安裝:
sudo pip install docutils sudo pip install rst2pdf
-
建議用pip + virtualenv來管理Python包
安裝和基本使用
-
安裝(再次推薦用virtualenv管理Python包):
sudo pip install sphinx
-
快速開始:
mkdir mydoc && cd mydoc sphinx-quickstart
-
簡單的嚮導，大部分選默認值即可
-
會產生配置文件conf.py以及Makefile
-
用make來產生目標格式的文檔
當然啦，需要你的系統裏裝過easy_install才能執行。
關於easy_install，我暫時把它理解爲一個類似apt-get的東東。
這一次MacOS又給了我個驚喜，居然缺省安裝了，so sweet~~~
Ubuntu上安裝起來也簡單：
sudo apt-get install python-setuptools 就好
2.1：使用sphinx
安裝 Sphinx
$ easy_install sphinx
創建目錄
進入你要創建文檔的目錄，例如要創建在目錄/home/wwwroot/doc下
cd /home/wwwroot/doc
創建文檔項目
sphinx-quickstart
程序會提示輸入一些選項，如輸入根目錄,大部分使用默認選項，直接按回車即可。
運行 sphinx-quickstart 命令後，在工作目錄中會出現類似 清單 5 的文件。
清單 5. 工作目錄的列表
. ├── Makefile ├── _build ├── _static ├── conf.py └── index.rst
讓我們詳細研究一下每個文件。
- Makefile：編譯過代碼的開發人員應該非常熟悉這個文件，如果不熟悉，那麼可以將它看作是一個包含指令的文件，在使用 make 命令時，可以使用這些指令來構建文檔輸出。
- _build：這是觸發特定輸出後用來存放所生成的文件的目錄。
- _static：所有不屬於源代碼（如圖像）一部分的文件均存放於此處，稍後會在構建目錄中將它們鏈接在一起。
- conf.py：這是一個 Python 文件，用於存放 Sphinx 的配置值，包括在終端執行 sphinx-quickstart 時選中的那些值。
- index.rst：文檔項目的 root 目錄。如果將文檔劃分爲其他文件，該目錄會連接這些文件。
3：語法
4：指令
4.1 index
This is a Title ffrom example3
==================================
.. index::
pair: Icon box; Tutorial
pair: Node; Tutorial
pair: Headline; Tutorial
pair: Body text; Tutorial
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.
Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles.
Lists can be unnumbered like:
* Item Foo
會在頁面上index形式
點擊相應index進入
x：參考
http://wiki.jerrypeng.me/rest-tjlug/
--sphinx
http://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/
http://www.jb51.net/article/26948.htm
https://github.com/xunxuny/zh-sphinx-doc/blob/master/index.rstThat has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.
Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles.
Lists can be unnumbered like:
* Item Foo