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/">

标签内的节点( documentparagraph …)在 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/">