Appreciate the explanation of source path configuration which I hadn't fully understand. And the summary of various modalities for error handling in a program setting as well as directly answering the post.

The indentation which currently is pretty easy to identify/correct in individual reST text documents is harder to deal when batch processing many documents from multiple authors.  One way or another the errors are identified when the text source is handed off to the docutils library.  But has someone authored a batch corrector/reformator for multiple reST text source with some common author errors like indentation?


On Wed, May 22, 2013 at 3:57 PM, David Goodger <> wrote:
On Wed, May 22, 2013 at 8:17 AM, Peter L. Soendergaard
<> wrote:
> Hi,
> I am running docutils.core.publish_string inside some python scripts and
> I need to process a lot of REST files from other people, and they often
> contains errors. I need to do some preprocessing to the files before
> passing them onto docutils, so that is why I call publish_string from
> inside of Python instead of the command line tools.
> Currently, I just see errors and warnings on the command line like:
> <string>:73: (ERROR/3) Unexpected indentation.
> <string>:74: (WARNING/2) Block quote ends without a blank line;
> unexpected unindent.
> Are there some parameters that I can pass onto publish_string so that I
> can capture the error output instead of it going straight to stderr?
> Or some better method than calling publish_string ?

publish_string seems like the right API for your use case.

You can capture the text of the system messages by assigning a
file-like object to the "warning_stream" setting. E.g. a
StringIO.StringIO object or a custom object with a "write" method.
This stream is used by docutils.utils.Reporter; the stream's write
method is called once per error/warning. <stderr> is the default if no
alternate stream is passed in.

Or you could set "halt_level" appropriately (and "traceback" to True)
to catch exceptions in try/except blocks.


Tip: the "source_path" parameter to publish_string will let you pass
the source text's filename/path, which will then be reported in the
system messages (currently only "<string>", because Docutils doesn't
know where the text came from).

David Goodger <>

Try New Relic Now & We'll Send You this Cool Shirt
New Relic is the only SaaS-based application performance monitoring service
that delivers powerful full stack analytics. Optimize and monitor your
browser, app, & servers with just a few lines of code. Try New Relic
and get this awesome Nerd Life shirt!
Docutils-users mailing list

Please use "Reply All" to reply to the list.

Michael G. Prisant