>>> from env_helper import info; info()
页面更新时间: 2024-01-17 15:46:20
运行环境:
Linux发行版本: Debian GNU/Linux 12 (bookworm)
操作系统内核: Linux-6.1.0-17-amd64-x86_64-with-glibc2.36
Python版本: 3.11.2
6.1. Python中的Docutils模块介绍¶
6.1.1. 什么是Docutils¶
Docutils项目的主要是为了创造一套将纯文本转换为一些常用格式的工具,这些常用格式包括:HTML、XML和LaTeX。 请事先了解 reStructuredText 的基础知识。
已经支持的包括:
独立的文本文件
PEP (Python Enhancement Proposals)
将会被支持的包括:
Python模块或者包中的内联文档
电子邮件(RFC822格式的邮件头、引用、签名和MIME 段)
Wiki格式
混合的文档,例如将多个的章节合并到一本书中
所发现的其他文件格式
使用 pip 安装:
pip install docutils
在 Debian / Ubuntu 下安装:
sudo apt install -y python3-docutils
如果你已经有了一个 .rst
文档,你可以使用:
cd <archive_directory_path>/tools
rst2html example.rst example.html
来生成 example.rst
的HTML文档。
6.1.2. Docutils的构成¶
由以下几个部分构成:
一个软件包 (包 docutils)
很多有用的小工具,在 tools 目录下,例如 rst2html.py 可以将 reStructuredText 转换成 HTML 页面。
一套测试用例
详细的文档
如果你想获得Docutils的具体实现方式,可以通过查看 PEP 258 。
Docutils是用Python实现的。
6.1.3. 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文件。
Create a parser:
>>> import docutils.parsers.rst
Several optional arguments may be passed to modify the parser’s behavior. Please see
Customizing the Parser
_ below for details.Gather input (a multi-line string), by reading a file or the standard input:
Create a new empty
docutils.nodes.document
tree:
>>> parser = docutils.parsers.rst.Parser()
>>> # document = docutils.utils.new_document(source, settings)
See docutils.utils.new_document()
for parameter details.
Run the parser, populating the document tree:
parser.parse(':ref:`6.0.3 to 6.0.4 changes <changelog-6-0-4>`')
>>> import docutils.nodes
>>> import docutils.parsers.rst
>>> import docutils.utils
>>>
>>> def parse_rst(text: str) -> docutils.nodes.document:
>>> parser = docutils.parsers.rst.Parser()
>>> components = (docutils.parsers.rst.Parser,)
>>> settings = docutils.frontend.OptionParser(components=components).get_default_values()
>>> document = docutils.utils.new_document('<rst-doc>', settings=settings)
>>> parser.parse(text, document)
>>> return document
>>> class MyVisitor(docutils.nodes.NodeVisitor):
>>>
>>> def visit_reference(self, node: docutils.nodes.reference) -> None:
>>> """Called for "reference" nodes."""
>>> print(node)
>>>
>>> def unknown_visit(self, node: docutils.nodes.Node) -> None:
>>> """Called for all other node types."""
>>> pass
>>> doc = parse_rst('spam spam lovely spam')
>>> visitor = MyVisitor(doc)
>>> doc.walk(visitor)
/tmp/ipykernel_37099/1594365319.py:8: DeprecationWarning: The frontend.OptionParser class will be replaced by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
settings = docutils.frontend.OptionParser(components=components).get_default_values()
False