以编程方式使用特定于 Sphinx 的指令解析 .rst 文件

【问题标题】：Parsing .rst files with Sphinx-specific directives programmatically以编程方式使用特定于 Sphinx 的指令解析 .rst 文件
【发布时间】：2011-11-14 17:05:23
【问题描述】：

我希望能够在 Python 中解析基于 sphinx 的 rst 以进行进一步处理和检查。比如：

import sphinx
p = sphinx.parse("/path/to/file.rst")
do_something_with(p)

似乎在 docutils 中使用 docutils.core.publish_file 有可能实现：

publish_file(open("/path/to/file.rst")

但这对 sphinx 特定指令等一无所知...

【问题讨论】：

标签： python python-sphinx docutils

【解决方案1】：

您可以在最终写入之前使用Sphinx Extensions 进行自定义处理。文档中有一个很好的入门示例项目，其中讨论了允许您自定义 Sphinx 的各种钩子。

根据您要执行的操作，您可能需要提供您的 do_something 函数作为这些事件之一的回调参数。

doctree-resolved(app, doctree, docname)
html-page-context(app, pagename, templatename, context, doctree)

然后你可以像下面这样扩展 sphinx

def setup(app):
    app.connect('doctree-resolved', do_something)

如果 Sphinx 教程中的示例不够详细，Doug Hellmann 也有一个 blog post 关于为 Sphinx 创建拼写检查器。我发现它对我之前写的 Sphinx 扩展很有用。

【讨论】：