LInux下帮助文件转HTML

最新推荐文章于 2021-05-15 08:36:53 发布

nerissa

最新推荐文章于 2021-05-15 08:36:53 发布

阅读量1.3k

点赞数

分类专栏： Linux系统服务

Linux系统服务专栏收录该内容

28 篇文章 0 订阅

订阅专栏

细心的哥们，肯定看过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生成的。