程序化解析带有Sphinx特定指令的.rst文件

Question

我想在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特有的指令等内容并不了解……

Answer 1

你可以使用Sphinx扩展来在最终写入之前进行自定义处理。文档中有一个非常好的入门示例项目，讨论了各种钩子，这些钩子可以让你自定义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还有一篇博客文章，讲的是如何为Sphinx创建拼写检查器。我发现这对我之前写的Sphinx扩展是一个很有用的参考。