CODEWITHSUNDEEP
pythonpython-sphinx
Augusto T.
Augusto T.

Reputation: 177

How to get a list of warnings from sphinx compilation

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.

Upvotes: 4

Views: 2522

Answers (2)

mzjn
mzjn

Reputation: 51012

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()

Upvotes: 5

Steve Piercy
Steve Piercy

Reputation: 15065

Assuming you used sphinx-quickstart to generate your initial Sphinx documentation set with a makefile, then you can use make to build docs, which in turn uses the Sphinx tool sphinx-build. You can pass the -w <file> option to sphinx-build to write warnings and errors to a file as well as stderr.

Note that options passed through the command line override any other options set in the makefile and conf.py.

Upvotes: 3

Related Questions