How to get a list of warnings from sphinx compilation

Question

I am developing a sphinx based collaborative writing tool. Users access the web application (developed in python/Flask) to write a book in sphinx and compile it to pdf.

I have learned that in order to compile a sphinx documentation from within python I should use

import sphinx
result = sphinx.build_main(['-c', 'path/to/conf',
                            'path/to/source/', 'path/to/out'])

So far so good.

Now my users want the app to show them their syntax mistakes. But the output (result in the example above) only gives me the exit code.

So, how do I get a list of warnings from the build process?

Perhaps I am being too ambitious, but since sphinx is a python tool, I was expecting to have a nice pythonic interface with the tool. For example, the output of sphinx.build_main could be a very rich object with warnings, line numbers...

On a related note, the argument to the method sphinx.build_main looks just like a wrapper to the command line interface.

Answer 1

sphinx.build_main() calls sphinx.cmdline.main(), which in turn creates a sphinx.application.Sphinx object. You could create such an object directly (instead of "making system calls within python"). Use something like this:

import os
from sphinx.application import Sphinx

# Main arguments 
srcdir = "/path/to/source"
confdir = srcdir
builddir = os.path.join(srcdir, "_build")
doctreedir = os.path.join(builddir, "doctrees")
builder = "html"

# Write warning messages to a file (instead of stderr)
warning = open("/path/to/warnings.txt", "w")

# Create the Sphinx application object
app = Sphinx(srcdir, confdir, builddir, doctreedir, builder, 
             warning=warning)

# Run the build
app.build()