Python中的Docutils模块介绍

作者:	A.TNG (翻译整理)
邮箱:	[e-mail]
参考:	document of Docutils

什么是Docutils

Docutils项目的主要是为了创造一套将纯文本转换为一些常用格式的工具，这些常用格式包括：HTML、XML和LaTeX。请事先了解 reStructuredText 的基础知识。

已经支持的包括：

• 独立的文本文件
• PEP (Python Enhancement Proposals)

将会被支持的包括：

• Python模块或者包中的内联文档
• 电子邮件（RFC822格式的邮件头、引用、签名和MIME 段）
• Wiki格式
• 混合的文档，例如将多个的章节合并到一本书中
• 所发现的其他文件格式

使用方法

解开下载的压缩包，并安装Docutils，下面的命令会帮助生成所有相关文档。

cd <archive_directory_path>/tools

./buildhtml.py ../

在Windows系统上可以使用：

cd <archive_directory_path>/tools

python buildhtml.py ..

如果你已经有了一个.rst文档，你可以使用：

cd <archive_directory_path>/tools

python rst2html example.rst example.html

来生成example.rst的HTML文档。

Docutils的构成

由以下几个部分构成：

• 一个软件包 (包 docutils)
• 很多有用的小工具，在 tools 目录下，例如 rst2html.py 可以将 reStructuredText 转换成 HTML 页面。
• 一套测试用例
• 详细的文档

如果你想获得Docutils的具体实现方式，可以通过查看 PEP 258 。

Docutils是用Python实现的。

Docutils的版本策略

我们的版本发布策略是“尽早和尽快的发布版本”，我们有自动生成的版本快照，通常包含了最新的代码，随着项目的成熟，我们将制定一份正式的版本控制计划，不过到现在为止，还没有相关的动作。

Docutils的工具集

• buildhtml.py

  • 可以使用buildhtml.py将目录下的所有.txt文件转换成.html文件，该操作也将包含其下的子目录。使用方法：

    buildhtml.py [options] [<directory> ...]

• rst2html.py

  • 通过使用rst2html.py可以将单独的reStructuredText文本文件转换成HTML文件，适用于当前流行的浏览器，并支持CSS。

    rst2html.py test.txt test.html

• rstpep2html.py

  • 通过使用rstpep2html.py可以将新的用reStructuredText格式编写的PEP转换成HTML。

    rstpep2html.py pep-0287.txt pep-0287.html

• rst2s5.py

  • 使用rst2s5.py可以将单独的reStructuredText文本文件转换成符合 S5 规范的(X)HTML文件。

    rst2s5.py slides.txt slides.html

• rst2latex.py

  • 通过使用rst2latex.py可以将单独的reStructuredText文本文件转换成LaTeX2e。

    rst2latex.py test.txt test.tex

• rst2xml.py

  • 通过使用rst2xml.py可以将单独的reStructuredText文本文件转换成XML文件。这是标准的XML文件。

官方网站

http://docutils.sourceforge.net/