Use better error messages for unsupported markup in LaTeX documents.

sphinx/application.py

@@ -19,14 +19,8 @@ from cStringIO import StringIO
 from docutils import nodes
 from docutils.parsers.rst import directives, roles
 
-import sphinx
+# create the error classes before importing the rest of Sphinx, so that
-from sphinx.roles import xfileref_role, innernodetypes
+# they can be imported in a circular fashion
-from sphinx.config import Config
-from sphinx.builder import builtin_builders, StandaloneHTMLBuilder
-from sphinx.directives import desc_directive, target_directive, additional_xref_types
-from sphinx.environment import SphinxStandaloneReader
-from sphinx.util.console import bold
-
 
 class SphinxError(Exception):
     """
@@ -56,6 +50,15 @@ class ExtensionError(SphinxError):
         return parent_str
 
 
+import sphinx
+from sphinx.roles import xfileref_role, innernodetypes
+from sphinx.config import Config
+from sphinx.builder import builtin_builders, StandaloneHTMLBuilder
+from sphinx.directives import desc_directive, target_directive, additional_xref_types
+from sphinx.environment import SphinxStandaloneReader
+from sphinx.util.console import bold
+
+
 # List of all known core events. Maps name to arguments description.
 events = {
     'builder-inited': '',

sphinx/builder.py

@@ -36,6 +36,7 @@ from sphinx.environment import BuildEnvironment, NoUri
 from sphinx.highlighting import PygmentsBridge
 from sphinx.util.console import bold, purple, darkgreen
 from sphinx.search import js_index
+from sphinx.application import SphinxError
 
 try:
     import json
@@ -902,7 +903,6 @@ class JSONHTMLBuilder(SerializingHTMLBuilder):
 
     def init(self):
         if json is None:
-            from sphinx.application import SphinxError
             raise SphinxError('The module simplejson (or json in Python >= 2.6) '
                               'is not available. The JSONHTMLBuilder builder '
                               'will not work.')
@@ -1030,7 +1030,7 @@ class LaTeXBuilder(Builder):
                         self.warn('%s: toctree contains ref to nonexisting file %r' %
                                   (docname, includefile))
                     else:
-                        sof = addnodes.start_of_file()
+                        sof = addnodes.start_of_file(file=includefile)
                         sof.children = subtree.children
                         newnodes.append(sof)
                 toctreenode.parent.replace(toctreenode, newnodes)
@@ -1047,6 +1047,7 @@ class LaTeXBuilder(Builder):
             tree = new_tree
         largetree = process_tree(indexfile, tree)
         largetree.extend(appendices)
+        largetree['file'] = indexfile
         self.info()
         self.info("resolving references...")
         self.env.resolve_references(largetree, indexfile, self)

sphinx/environment.py

@@ -44,6 +44,7 @@ from docutils.transforms.parts import ContentsFilter
 from sphinx import addnodes
 from sphinx.util import movefile, get_matching_docs, SEP, ustrftime
 from sphinx.directives import additional_xref_types
+from sphinx.application import SphinxError
 
 default_settings = {
     'embed_stylesheet': False,
@@ -542,7 +543,6 @@ class BuildEnvironment:
             pub.publish()
             doctree = pub.document
         except UnicodeError, err:
-            from sphinx.application import SphinxError
             raise SphinxError(err.message)
         self.filter_messages(doctree)
         self.process_dependencies(docname, doctree)

sphinx/latexwriter.py

@@ -22,6 +22,7 @@ from docutils.writers.latex2e import Babel
 from sphinx import addnodes
 from sphinx import highlighting
 from sphinx.locale import admonitionlabels, versionlabels
+from sphinx.application import SphinxError
 from sphinx.util import ustrftime
 from sphinx.util.texescape import tex_escape_map
 from sphinx.util.smartypants import educateQuotesLatex
@@ -65,6 +66,9 @@ FOOTER = r'''
 class collected_footnote(nodes.footnote):
     """Footnotes that are collected are assigned this class."""
 
+class UnsupportedError(SphinxError):
+    category = 'Markup is unsupported in LaTeX'
+
 
 class LaTeXWriter(writers.Writer):
 
@@ -209,6 +213,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.highlightlinenothreshold = sys.maxint
         self.written_ids = set()
         self.footnotestack = []
+        self.curfilestack = []
         if self.elements['docclass'] == 'manual':
             if builder.config.latex_use_parts:
                 self.top_sectionlevel = 0
@@ -232,6 +237,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def visit_document(self, node):
         self.footnotestack.append(self.collect_footnotes(node))
+        self.curfilestack.append(node['file'])
         if self.first_document == 1:
             # the first document is all the regular content ...
             self.body.append(BEGIN_DOC % self.elements)
@@ -262,6 +268,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.body.append('\n\\resetcurrentobjects\n')
         # and also, new footnotes
         self.footnotestack.append(self.collect_footnotes(node))
+        self.curfilestack.append(node['file'])
 
     def collect_footnotes(self, node):
         fnotes = {}
@@ -281,6 +288,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def depart_start_of_file(self, node):
         self.footnotestack.pop()
+        self.curfilestack.pop()
 
     def visit_highlightlang(self, node):
         self.highlightlang = node['lang']
@@ -360,9 +368,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
             try:
                 self.body.append(r'\%s{' % self.sectionnames[self.sectionlevel])
             except IndexError:
-                from sphinx.application import SphinxError
+                raise UnsupportedError(
-                raise SphinxError('too many nesting section levels for LaTeX, '
+                    '%s:%s: too many nesting section levels for '
-                                  'at heading: %s' % node.astext())
+                    'LaTeX, at heading: %s' % (self.curfilestack[-1],
+                                               node.line or '', node.astext()))
             self.context.append('}\n')
         elif isinstance(parent, (nodes.topic, nodes.sidebar)):
             self.body.append(r'\textbf{')
@@ -555,7 +564,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def visit_table(self, node):
         if self.table:
-            raise NotImplementedError('Nested tables are not supported.')
+            raise UnsupportedError('%s:%s: nested tables are not yet implemented.' %
+                                   (self.curfilestack[-1], node.line or ''))
         self.table = Table()
         self.tablebody = []
         # Redirect body output until table is finished.
@@ -621,8 +631,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def visit_entry(self, node):
         if node.has_key('morerows') or node.has_key('morecols'):
-            raise NotImplementedError('Column or row spanning cells are '
+            raise UnsupportedError('%s:%s: column or row spanning cells are '
-                                      'not implemented.')
+                                   'not yet implemented.' %
+                                   (self.curfilestack[-1], node.line or ''))
         if self.table.col > 0:
             self.body.append(' & ')
         self.table.col += 1