LInux下帮助文件转HTML

细心的哥们，肯定看过LINUX帮助文件所在目录文件的格式 ，后缀是RST的。但如果要想以HTML格式查看的话，就要用以下方法了：
先说明一下：要想转换成功，必须是源码包
一、什么是.rst：

rst是reStructuredText的缩写。在reStructuredText的说明文档(http://docutils.sourceforge.net/rst.html)中，有这么一段话可以很好地解释reStructuredText：

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings),
for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation
of the StructuredText and Setext lightweight markup systems.

The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful
enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.

同时，在wikipedia(http://en.wikipedia.org/wiki/ReStructuredText)中，对于reStructuredText的解释如下：
The reStructuredText (frequently
abbreviated as reST) project is part of the Pythonprogramminglanguage Docutils
project of the Python Doc-SIG (Documentation Special Interest Group). The goal of the project is to create a set of tools for Python similar to Javadoc for
Java or POD for Perl. Docutils can extract comments and information from Python programs,
and format them into various forms of useful program documentation.
The term reStructuredText is
most frequently used to refer to the reST markup format developed by the reST project. In this sense, reST is a lightweightmarkuplanguage designed
to be both (a) processable by documentation-processing software such as Docutils, and (b) easily readable by human programmers who are reading and writing Python sourcecode.
reStructuredText is sometimes abbreviated as RST, ReST,
or reST. This can create confusion with RepresentationalState
Transfer(REST),
an unrelated technology.

可见，rst是一种轻量级标记语言，利于多人协同写作。可以借助Docutils对rst进行文档处理，从conf.py中提取信息，解析转化成我们熟悉的文档格式，如html或者pdf。

二、解析转化.rst为html：

在doc文件夹中，conf.py里有pygments_style
= 'sphinx'，可见，对doc文件夹下的rst文件，我们需要用sphinx来进行解析转化。且在conf.py中的output的选项有LaTeX，manual
page，Texinfo，HTML，我熟悉的只有HTML，所以，我选择将doc下的rst文件转为html文件。

1）安装sphinx:
在cmd中输入命令 easy_install
-U Sphinx
在安装过程中，你会发现，sphinx依赖于docutils和pygment：
docutils是sphinx的基础,其实使用docutils自带的脚本可以进行rst转html的工作,但是无法识别一些扩展的元素和代码高亮,这些都是通过sphinx实现的。
pygments是python实现的对python代码进行高亮的扩展,他和sphinx协同工作就可以在生成的文档中对代码进行高亮。pygments的官网还有很多其他代码高亮的项目链接,包括js，java等。
LINUX环境中：下载sphinx源码包后，运行python
setup.py install就会自动安装相关依赖包了。如果依赖包无法安装，就只能手工一个一个的装了，直到 sphinx安装程序识别为止

2）转rst为html:
sphinx安装完毕后，就可以将rst转成html了。在cmd下的命令为：
sphinx-build -b html <srcDir> <dstDir>
srcDir是makefile和conf.py所在的目录，dstDir则可以随意指定，这里cd到doc的所在的文件夹下，执行：
sphinx-build -b html doc/ doc_build/
执行完成后，就可以在doc_build文件夹下看到rst文件对应的html文件了。

3）下面的网址，是一些有关sphinx和reStructuredText的补充内容：

https://developer.ridgerun.com/wiki/index.php/How_to_generate_sphinx_documentation_for_python_code_running_in_an_embedded_system

http://sphinx-doc-zh.readthedocs.org/en/latest/rest.html

http://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/

PS：当然，也可以用Pandoc(下载地址是：http://johnmacfarlane.net/pandoc/installing.html)进行rst到html的转换。Pandoc安装成功，并在环境变量中设置Pandoc程序的Path后，cd到需要转换的文件夹下，在cmd中输入命令：
for /f "delims=" %i in ('dir /b *.rst') do @(pandoc "%i" -o "%~ni.html")
或者
for %i in (*.rst) do @(pandoc "%i" -o "%~ni.html")
便可以在该目录下看到对应的html文件。可以看到，用Pandoc生成的html文件，效果完全不及sphinx生成的。