I'm generating reStructuredText from literate source files. How can I make error messages to point to the original sources?

[Clément Pit-Claudel]

(cross-posted from docutils-develop)

Hi all,

I'm using Sphinx to compile documents obtained by preprocessing literate source files. I currently use a two-phase build system, in which I first translate to reStructuredText using a custom pre-processor, and then export to HTML with Sphinx. The preprocessing phase is very simple: it removes comment markers here and there and indents code to produce a valid reStructuredText document.

Unfortunately, this setup means that line numbers in error messages refer to the preprocessed version of the document — not the original one. I'd like to teach the reStructuredText parser to report errors relative to the original document instead (and, when snippets are printed as part of an error message, to print snippets from the original document too). I have already extended my preprocessor to create a table mapping each line in the reStructuredText output to the corresponding line in the original source file, so it's mostly a matter of knowing where to plug this table.

What's the right way to proceed? Should I write a Sphinx reader instead of a docutils parser?

Thanks,
Clément.

PS: For completeness, the parser that I currently use looks like this::

class LiterateParser(docutils.parsers.Parser):
supported = ('lit')
settings_spec = ('Literate Parser Options', None, ())
config_section = 'Literate parser'
config_section_dependencies = ('parsers',)

def __init__(self):
self.parser = docutils.parsers.rst.Parser()

def get_transforms(self):
return self.parser.get_transforms()

@staticmethod
def preprocess(literate_string):
…

def parse(self, literate_string, document):
"""Parse `inputstring` and populate `document`, a document tree."""
linemap, rst_string = LiterateParser.preprocess(literate_string)
self.parser.parse(rst_string, document)

The source files look like this::

/// A literate file!
/// ================
///
/// Here is some *code*.

int main() { return 0; }

And the generated reStructuredText looks like this::

A literate file!
================

Here is some *code*.

.. literate-block::

int main() { return 0; }