自述: Docutils 0.15b.dev

作者

David Goodger

联系

goodger@python.org

日期

$Date: 2018-06-10 00:22:09 +0200 (So, 10. Jun 2018) $

网站

http://docutils.sourceforge.net/

版权

本文档已置于公共领域。

目录

• 自述: Docutils 0.15b.dev

  • 快速开始

  • 目的

  • 发布和快照

  • 要求

    • Python3兼容性

  • 项目文件和目录

  • 安装

    • GNU/Linux，BSD，Unix，Mac OS X 等

    • Windows

  • 用法

  • 转换文档

  • 运行测试套件

  • 获得帮助

快速开始

这适用于那些想要快速起步和跑步的人。

1. Docutils需要Python(2.6或更高版本)，可从中获得

   http://www.python.org/

   有关详情，请参阅以下 Requirements

2. 使用最新的Docutils代码。从 Subversion存储库 或快照中获取代码:

   https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/

   有关详细信息，请参阅下面的 Releases & Snapshots 。

3. 将tarball解压缩到临时目录中(不 直接在Python的 site-packages 中)，转到通过展开存档创建的目录，然后运行 setup.py install 。在Windows系统上，双击 install.py 可能就足够了。

   有关详情，请参阅下面的安装

4. 使用前端脚本转换reStructuredText文档。试试这个例子:

   rst2html.py FAQ.txt FAQ.html         (Unix)
   python tools/rst2html.py FAQ.txt FAQ.html  (Windows)
   

   有关详情，请参阅下面的 Usage 。

目的

Docutils项目的目的是创建一组工具，用于将明文文档处理成有用的格式，例如HTML，XML和LaTeX。已实施对以下来源的支持:

• 独立文件。

• PEPs (Python增强建议).

计划支持以下来源:

• 来自Python模块和包的内联文档，使用命名空间上下文提取。

• 电子邮件(RFC-822标题，引用的摘录，签名，MIME部分)。

• Wiki，具有 “wiki links” 的全局参考查找。

• 复合文档，例如多章文件合并到一本书中。

• 和其他人一样被发现。

发布和快照

虽然我们正在尝试遵循 “早期和经常发布” 政策，但会经常添加功能。由于Subversion存储库中的代码通常处于无错状态，因此我们建议您使用当前快照。

要获取快照，请转到代码页并单击下载快照按钮:

• Docutils代码，文档，前端工具和测试: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/

• 沙盒(实验，贡献代码): https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/

要及时了解最新动态，请定期下载快照的新副本或使用 Subversion存储库 的工作副本。

要求

要运行代码，必须安装 Python 。 Docutils兼容Python版本2.6,2.7和版本3.3到3.5(参见 Python 3兼容性 )。

Docutils使用以下软件包来增强功能(如果已安装):

• Python成像库 或PIL用于某些图像处理操作。

• Pygments 语法高亮显示器用于 code 指令和角色的内容。

Python3兼容性

Docutils代码库是为Python 2编写的，并使用 “按需” 翻译来 移植到Python 3 。

• setup.py 脚本在 build/ 中生成Python 3兼容源，并在 安装 期间使用Python 3在 tests3/ 子目录中进行测试。

• tools/ 子目录中的脚本可以使用所有受支持的Python版本而无需转换。

• 要在不安装的情况下转换源代码(例如进行测试)，请运行 python3 setup.py构建 。

• 编辑源代码时，请对Python的2个版本的文件进行更改，然后重新运行build命令。

项目文件和目录

• README.txt：你正在读它。

• COPYING.txt: 非公共域文件的公共域专用和版权详细信息(大多数是PD)。

• FAQ.txt: 常见问题(有答案！)。

• RELEASE-NOTES.txt: 最近发布的主要变化摘要。

• HISTORY.txt: 详细的更改日志，适用于当前和之前的所有项目版本。

• BUGS.txt: 已知的错误，以及如何报告错误。

• THANKS.txt: 贡献者名单。

• setup.py: 安装脚本。 请参阅下面的 “Installation” 。

• install.py: 快速和脏的安装脚本。跑吧。但是，对于任何类型的自定义或帮助，必须使用setup.py。

• docutils: 项目源目录，作为Python包安装。

• docs: 项目文档目录。阅读 docs/index.txt 了解概述。

• docs/user: 项目用户文档目录。包含以下文档等:

  • docs/user/tools.txt: Docutils前端工具

  • docs/user/latex.txt: Docutils LaTeX作家

  • docs/user/rst/quickstart.txt: ReStructuredText入门

  • docs/user/rst/quickref.html: 快速reStructuredText(仅限HTML)

• docs/ref：项目引用目录。 docs/ref/rst/restructuredtext.txt 是reStructuredText引用。

• 许可证：包含非公共域文件的许可证文件副本的目录。

• 工具：Docutils前端工具的目录。有关文档，请参阅 docs/user/tools.txt 。

• 测试：单元测试。不需要使用该软件，但如果您计划修改它，则非常有用。请参阅下面的“运行测试套件”。

在Python下安装时生成的目录3:

• build: 转换来源。

• test3: 转换测试。

安装

第一步是在一个临时目录中扩展 .tgz 存档(不 直接在Python的 site-packages 中)。它包含一个distutils安装文件 “setup.py” 。特定于操作系统的安装说明如下

GNU/Linux，BSD，Unix，Mac OS X 等

1. 打开一个shell。

2. 转到通过展开存档创建的目录:

   cd <archive_directory_path>
   

3. 安装软件包(您可能需要root权限才能完成此步骤):

   su
   (enter admin password)
   python setup.py install
   

   如果python可执行文件不在您的路径上，则必须指定完整路径，例如 /usr/local/bin/python 。

   要安装特定的Python版本，请在安装调用中使用此版本，例如:

   python3.1 setup.py install
   

   要安装不同的Python版本，请对每个所需版本重复步骤3。最后安装的版本将用于 rst2 *.py 包装脚本的 shebang line 。

Windows

只需双击 install.py 即可。如果这不起作用，请尝试以下操作:

1. 打开DOS Box(命令外壳，MS-DOS提示符，或者这些天他们称之为的任何东西)。

2. 转到通过展开存档创建的目录:

   cd <archive_directory_path>
   

3. 安装包:

   <path_to_python.exe>\python setup.py install
   

   要安装特定的python版本，请为此版本指定Python可执行文件。

   要安装不同的Python版本，请对每个所需版本重复步骤3。

可选步骤:

• 运行测试套件

• 转换文档

用法

解压 “tools” 子目录中有许多前端工具。在Unix下安装将副本放在PATH中。您可能希望从 “rst2html.py” 前端工具开始。大多数工具最多需要两个参数，即源路径和目标路径，STDIN和STDOUT是默认值。使用前端工具的 “-help” 选项可获取有关选项和参数的详细信息。有关完整文档，请参阅Docutils前端工具(docs/user/tools.txt)。

包模块不断发展和发展。 docutils.statemachine 模块可以独立使用。它包含大量的内联文档(当然是reStructuredText格式)。

欢迎捐款！

转换文档

解压缩并安装Docutils软件包后，以下shell命令将为所有包含的文档生成HTML:

cd <archive_directory_path>/tools
./buildhtml.py ../

在Windows系统上，键入:

cd <archive_directory_path>\tools
python buildhtml.py ..

对于快照，<archive_directory_path> 的最终目录名是 “docutils” 。对于正式版本，该目录可以称为 “docutils-X.Y.Z” ，其中 “X.Y.Z” 是发行版本。另外:

cd <archive_directory_path>
tools/buildhtml.py --config=tools/docutils.conf          (Unix)
python tools\buildhtml.py --config=tools\docutils.conf   (Windows)

某些文件可能会生成系统消息(警告和错误)。 docs/user/rst/demo.txt 文件(在归档目录下)包含五个故意错误。 (他们测试错误报告机制！)

运行测试套件

测试套件记录在 Docutils Testing (docs/dev/testing.txt)中。

要运行整个测试套件，请打开shell并使用以下命令:

cd <archive_directory_path>/test
./alltests.py

在Windows下，键入:

cd <archive_directory_path>\test
python alltests.py

对于Python 3的测试，请使用转换后的测试套件:

cd <archive_directory_path>/test3
python3 alltests.py

您应该看到一长串的句点，每个测试一个，然后是这样的摘要:

Ran 1111 tests in 24.653s

OK
Elapsed time: 26.189 seconds

测试次数会随着时间的推移而增加，报告的时间将取决于运行测试的计算机。两次之间的差异表示设置测试所需的时间(导入模块，创建数据结构等)。

如果任何测试失败，请 打开错误报告 或 发送电子邮件 (参见 Bugs)。请包括所有相关输出，有关您的操作系统，Python版本和Docutils版本的信息。要查看Docutils版本，请使用 rst2* 前端之一或 tools/quicktest.py 和 --version 选项，例如:

cd ../tools
./quicktest.py --version

Windows用户键入这些命令:

cd ..\tools
python quicktest.py --version

获得帮助

如果您对Docutils或reStructuredText有任何疑问或需要帮助，请发送邮件至 Docutils-users 邮件列表。