收集的一些关于reStructuredText和Sphinx的资料¶
打算用reStructuredText和Sphinx重组自己平时所收集的一些资料，将其汇总形成一个个人资料库。结构化文件，编辑起来方便，存放也很方便，又能进行版本管理，又能支持多种格式的输出，没道理不喜欢这个。下面交这两天收集到的关于这方面的资料汇总一下。
关于reStructuredText的资料¶
安装ReST¶
当然，使用这个工具，需要python的支持了，所以得有pyhton才行，如果你是在Linux上，比如Ubuntu，那么Python早就安装好了的。
从源码安装¶
到下面地址下载docutils源码包：
http://docutils.sourceforge.net/index.html
解压后，在其目录执行： python setup.py install
使用easy_install 安装¶
使用easy_install 安装，如果还没安装这个工具的话，得先安装它，在 这里 获得安装程序，然后运行 python ez_setup.py install 。 安装好后，再在终端下执行 easy_install docutils ，即可。
测试¶
编辑一个文本，名为 test.rst ，内容为：:
Title
==========
哈哈，这里是内容
然后这里是链接： http://google.com
生成HTML，执行命令： `` rst2html test.rst test.html`` [1] ，这里在你的当前目录下，就会自动生成一个 test.html 文件了！
Note
如果没有指定输出的html文件，则只能看到html代码，而不能看到文件。
如果只是编辑一些单个的文件，就使用 rst2html 就够了，详细参数 [2] ：:
rst2html [参数] <源文件.rst> [目标文件.html]
如果不指定目标文件，而输出Html代码，并不生成文件
-r <levle> 设定报告级别，默认为 2
--tab-width=<width> 设定输出的缩进宽度，默认8个空格
--stylesheet-path=<file> 指定CSS文件
--embed-stylesheet 使用嵌入式CSS
--footnote-references=<format> 脚注格式。 barckets方括号 superscript上标
--compact-lists 忽略列表中多余的空行，默认 enabled
--config=<file> 指定配置文件
--footnote-backlinks 允许从脚注跳回原文，默认选项
--toc-top-backlinks 允许从标题跳回索引，默认选项
关于教程¶
reStructuredText简明教程： http://blog.csdn.net/jiyucn/archive/2008/03/07/2157189.aspx
这个应该不是原教程位置，是转发的。如果你英文比较好的话，也可以直接读英文版的快速入门教程：
Quick reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
关于Sphinx的资料¶
使用Sphinx将结构化文本生成文档，程序员完文档专用工具，特别是Python程序员。
创建Sphinx文档工程¶
创建目录，并使用 sphinx-quickstart 生成程 ([3] [4] )：
mkdir TestProject
cd TestProject/
~/TestProject$ sphinx-quickstart
Welcome to the Sphinx 1.0.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: ## 这里也可以不直接指定目录，如果是在已建好的目录中创建项目，则直接回车即可。
## 以下内容，为空的则是采用默认设置，直接回车。
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]:
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: TestProject
> Author name(s): wwq
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 0.1
> Project release [0.1]:
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]: y
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: y
> Create Windows command file? (Y/n) [y]: y
Finished: An initial directory structure has been created.
You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
操作完后，在你的目录下会生成下面这些目录及文件：
wyatt@wyatt-desktop:~/TestProject$ tree
.
├── _build
├── conf.py
├── index.rst
├── make.bat
├── Makefile
├── _static
└── _templates
在这个目录里面，可能建寻一些目录来存放rst源文件，当然也可以直接在这个目录里创建文件。
生成HTML¶
运行:
make html
运行时的提示：
wyatt@wyatt-desktop:~/TestProject$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.0.1
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in _build/html.
如提示所说，生成的文件被放在了 -build/html 目录中，进去打开吧：
参考资源索引¶
| [1] | 参考： http://shellexy.info/books/obp.rwpy4learner/html/ch02/WriteDocument.html |
| [2] | 参考： http://blog.csdn.net/jiyucn/archive/2008/03/07/2157189.aspx |
| [3] | 参考： http://shellexy.info/books/obp.rwpy4learner/html/ch02/WriteDocument.html#sphinx |
| [4] | 参考： http://code.google.com/p/pymotwcn/wiki/SphinxprojectHowto |