leo学习系列之七——文档生成rst3和sphinx

先看看网页在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 -U Sphinx
当然啦，需要你的系统里装过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：语法

参考：http://docutils.sourceforge.net/docs/user/rst/quickref.html

http://blog.csdn.net/quqi99/article/details/8537361

4：指令

http://docutils.sourceforge.net/docs/ref/rst/directives.html

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