Parsing .rst files with Sphinx-specific directives programmatically

Question

I would like to be able to parse sphinx based rst in Python for further processing and checking. Something like:

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

It seems that something is possible in docutils using the docutils.core.publish_file:

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

But that doesn't know anything about sphinx specific directives etc...

Answer 1

You can use Sphinx Extensions to do custom processing before the final write. There is a very good getting started example project in the documentation that discusses various hooks that allow you to customize Sphinx.

Depending on what you're trying to do, you may need to supply your do_something function as a call back argument to one of these events.

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

And then you can extend sphinx as follows

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

If the example in the Sphinx tutorial is not detailed enough, Doug Hellmann also has a blog post about creating a spell checker for Sphinx. I found it to be a useful reference for the Sphinx extension I had to write a while back.