如何将修改后的reStructuredText解析树反解析回RST文件
基于语法树反解析的RST代码块修改回写方案
完全可以替代原有基于正则的回写逻辑,核心流程基于docutils原生的RST双向转换能力实现,无需额外做字符串匹配:
核心实现步骤
- 复用现有基于docutils的解析链路:在已能遍历文档树定位Python代码块(对应节点类型为
nodes.literal_block、绑定language="python"属性)、完成代码格式化修改的基础上,不需要额外读取原文件做字符串替换。 - 引入反解析核心环节:直接调用docutils官方提供的原生RST Writer组件,将修改完成的文档树反向生成合法的RST格式文本,该组件的设计目标就是把docutils解析出的文档结构无损还原为标准RST语法,不会破坏非代码块内容的原有排版和语法标记。
- 文本生成完成后直接覆盖写入原RST文件即可。
参考实现代码
import docutils from docutils.core import publish_string from docutils import nodes # 读取原RST文件,解析为文档树 with open("target.rst", "r", encoding="utf-8") as f: rst_content = f.read() doc_tree = publish_string(rst_content, writer_name="doctree") # 遍历文档树完成代码块格式化(替换为你现有可运行的定位与格式化逻辑) def format_code_node(node): if isinstance(node, nodes.literal_block) and node.get("language") == "python": raw_code = node.astext() # 替换为实际的Python代码格式化逻辑(比如接入black库完成格式化) formatted_code = run_your_formatter(raw_code) # 把格式化后的内容替换为新的代码块节点,保留原节点的所有语法属性 node.replace_self( nodes.literal_block( formatted_code, formatted_code, **node.attributes ) ) doc_tree.walk(format_code_node) # 反解析环节:把修改后的文档树转回RST格式文本 rst_writer = docutils.writers.restructuredtext.Writer() final_rst = publish_string( input=doc_tree, writer=rst_writer, settings_overrides={"output_encoding": "utf-8"} ).decode("utf-8") # 覆盖原文件完成回写 with open("target.rst", "w", encoding="utf-8") as f: f.write(final_rst)
关键注意事项
- 不要混用其他格式的Writer组件:比如用HTML Writer、Markdown Writer生成的文本会丢失RST专属语法(比如交叉引用标记、自定义解释指令、脚注格式),必须使用
docutils.writers.restructuredtext下的专属RST Writer才能保证生成内容和原生RST语法兼容。 - 修改代码块节点时尽量保留原节点的属性:包括缩进级别、附带的指令选项(比如
:linenos:、:caption:),RST Writer会根据这些属性自动还原对应的RST语法标记,不会出现排版错乱。 - 对比原有正则方案的优势:基于语义节点的修改逻辑不会被代码块内的特殊字符(比如代码里出现的冒号、不规则缩进)触发误匹配,生成的RST永远保证语法合法,不会破坏原文件其他部分的内容。
这套方案和之前参考的@mbdevpl 提供的树遍历处理逻辑完全兼容,不需要改动已有的代码块定位、内容格式化逻辑,仅需补充文档树转RST文本的生成环节,即可完全替代原有正则匹配的回写流程。
内容的提问来源于stack exchange,提问作者user3064538
相关产品推荐
相关产品推荐

