sphinx---.rst轉.html的利器一枚
轉載請說明出處~~~^_^
在openERP的源碼中,doc文件夾下的自帶文檔都是.rst格式的,雖然以文本格式打開也能看,但閱讀起來極爲不便。
一、什麼是.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等。
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的補充內容:
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生成的。
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.