docutils 是一个用于处理纯文本文档的 Python 工具集，最著名的应用就是将 reStructuredText (reST) 格式的文件转换成其他格式，HTML、PDF、XML 等，它是 Sphinx 文档生成系统的核心依赖。
什么是 docutils？
docutils 是一个幕后英雄，你通常不会直接为它写一个复杂的程序，而是通过命令行或者将其作为其他工具（如 Sphinx）的依赖来使用它的强大功能。
它的核心功能包括：
- 解析器: 读取 reST 格式的文本文件。
- 树处理器: 将解析后的文本转换成中间的文档树结构。
- 写入器: 将文档树转换成最终的目标格式（如 HTML, LaTeX, ODT 等）。
如何下载和安装 docutils
docutils 在 Python Package Index (PyPI) 上发布，所以我们可以使用标准的 Python 包管理工具 pip 来安装。
推荐方法：使用 pip (最简单)
打开您的终端或命令提示符,然后运行以下命令：
pip install docutils
注意:
- 如果您使用的是 Python 3，并且系统同时安装了 Python 2 和 Python 3，建议使用
pip3来确保安装到正确的 Python 环境中：pip3 install docutils
- 如果您没有将
pip添加到系统环境变量中，可能需要使用python -m pip或python3 -m pip：python -m pip install docutils
安装完成后，您可以在 Python 代码中导入它,或者使用它附带的命令行工具。
如何使用 docutils
安装完成后，docutils 提供了两种主要的使用方式：命令行工具和 Python API。
使用命令行工具 (最常用)
docutils 安装后会自动添加几个命令行工具到您的系统路径中，最常用的是 rst2html.py (或 rst2html，取决于您的系统和 Python 版本)。
将 .rst 文件转换为 .html 文件
假设您有一个名为 example.rst 的文件,内容如下：
======================= 我的第一个 reST 文档 ======================= 这是一个使用 reStructuredText 格式的示例文档。 - 列表项 1 - 列表项 2 - 列表项 3 您可以查看 `docutils` 的 `__init__.py` 文件来了解更多信息。 更多信息请访问: `docutils 官网 <https://docutils.sourceforge.io/>`_。
在终端中，进入该文件所在的目录,然后运行：
# 使用 rst2html.py rst2html.py example.rst example.html # 或者在新版 Python 中，可能是 rst2html (不带 .py 后缀) rst2html example.rst example.html
执行后，会生成一个 example.html 文件,您可以在浏览器中打开它查看效果。
查看所有可用的转换器
您可以使用 -h 或 --help 参数查看所有可用的转换器：
rst2html.py --help
输出会类似这样,显示了所有支持的输入和输出格式：
...
This writer produces HTML. It accepts the following options:
...
Available Writers: html4css1, s5, xetex, pseudoxml, html, latex, odt, man,
xml, pseudoxml, s5, xetex, html4css1
...在 Python 代码中使用 (API)
您也可以在 Python 脚本中直接调用 docutils 的功能,这对于需要将文档转换功能集成到您自己的应用程序中的场景非常有用。
示例：将 reST 字符串转换为 HTML 字符串
import docutils.core
import docutils.writers.html4css1
# 1. 准备 reST 格式的字符串
rst_string = """
=======================
我的第一个 reST 文档
=======================
这是一个使用 reStructuredText 格式的示例文档。
- 列表项 1
- 列表项 2
- 列表项 3
更多信息请访问: `docutils 官网 <https://docutils.sourceforge.io/>`_。
"""
# 2. 使用 docutils.core.publish_string 进行转换
# writer_name='html4css1' 指定输出为 HTML4 格式
html_output = docutils.core.publish_string(
source=rst_string,
writer_name='html4css1'
)
# 3. 输出结果 (bytes 类型)
# 解码为字符串以便打印
print(html_output.decode('utf-8'))
示例：将 reST 文件转换为 HTML 文件
import docutils.core
# 输入和输出文件名
input_file = 'example.rst'
output_file = 'example_from_api.html'
# 1. 读取 reST 文件内容
with open(input_file, 'r', encoding='utf-8') as f:
rst_content = f.read()
# 2. 转换内容
# destination_path 指定了输出文件的路径
html_output = docutils.core.publish_string(
source=rst_content,
writer_name='html',
destination_path=output_file
)
print(f"文件已成功转换并保存到: {output_file}")
常见问题
Q: pip install docutils 失败怎么办？
A: 这通常是由于网络问题或权限问题导致的。
- 网络问题: 尝试使用国内镜像源。
pip install docutils -i https://pypi.tuna.tsinghua.edu.cn/simple
- 权限问题: 如果您没有管理员权限，可以尝试安装到用户目录。
pip install --user docutils
Q: 我需要转换 Markdown 文件，docutils 可以吗？
A: docutils 本身不直接支持 Markdown，您可以使用 pymdown-extensions 库，它为 docutils 提供了 Markdown 解析器。
安装方法：
pip install docutils pymdown-extensions
您可以使用一个特殊的 writer 名称来转换 Markdown 文件：
# 假设 your_markdown.md 是一个 Markdown 文件 rst2html.py --writer=markdown your_markdown.md output.html
或者，更常见的做法是使用专门的 Markdown 工具，如 Python-Markdown 库。
| 任务 | 命令 / 代码 |
|---|---|
| 安装 | pip install docutils |
| 命令行转换 | rst2html.py input.rst output.html |
| Python API 转换 | docutils.core.publish_string(source=rst_str, writer_name='html') |
希望这份详细的指南能帮助您顺利下载和使用 docutils！
