Docutils Hacker's Guide

date:

2020-11-12

reference:

https://docutils.sourceforge.io/docs/dev/hacking.html

Doctuils 是 Python 编写的通用文档处理软件，使用 reStructedText 作为 markup language。 提供了 rst2{html,man,xml,xetext} 等命令行工具（ pacman -Ql python-docutils | grep /usr/bin/ ）。

Docutils Hacker's Guide 简要解释了 Docutils 的工作原理： 将一个 rst 文件转换为目标格式的文档（比如 HTML）需要经过： Read ( docutils/readers ) -> Parse ( docutils/parsers ) -> Transform ( docutils/transforms )-> Write ( docutils/writers ) 四个阶段。

Parse 阶段将 Read 读取的文件解析为一棵节点树，目前仅实现了 reStructuredText parser ( docutils/parsers/rst )。对于如下 rst 文档:

My *favorite* language is Python_.

.. _Python: http://www.python.org/

使用 docutils/tools/quicktest.py 可以查看 rst 文档的节点树 （层级用缩进表示）:

<document source="test.txt">
<paragraph>
    My
    <emphasis>
        favorite
     language is
    <reference name="Python" refname="python">
        Python
    .
<target ids="python" names="python" refuri="http://www.python.org/">

标签内的节点（ document 、 paragraph ...）在 docutils/nodes.py 中都能找到对应的实现。 可以用 epydoc 查看节点的继承关系。

备注

树上的文本譬如 "My"、"language is"、"." 同样是节点， 对应的实现为 docutils.nodes.Text

Transform 阶段利用 📖 访问者模式 对语法树进行各种变换， 本例中 ExternalTargets transform ( docutils/transforms/references.py ) 会解析 reference 节点，寻找 ID 为 "python" 的 target 节点， 并设置 reference 节点的 refuri 属性。 使用 rst2pseudoxml 可以看到 Transform 阶段后的节点树:

<document source="test.txt">
<paragraph>
    My
    <emphasis>
        favorite
     language is
    <reference name="Python" refuri="http://www.python.org/">
        Python
    .
<target ids="python" names="python" refuri="http://www.python.org/">

评论

如果你有任何意见，请在此评论。 如果你留下了电子邮箱，我可能会通过 回复你。