Error message very hard to understand when provided with invalid doxygen xml file

[mquinson]

I had the following construct in one of my doxygen input file: @c <b>text</b>. This is obviously my mistake, but Doxygen still produces an XML file, containing the following invalid chunk: <computeroutput><bold>text</computeroutput>. Thanks Doxygen :)

When feeded with that file, breathe produces the following output. As you can see, the name of the parsed file is not even displayed.

reading sources... [ 50%] api-s4u                                                                                                                                    
Exception occurred:
  File "/usr/lib/python3/dist-packages/breathe/parser/__init__.py", line 90, in parse
    raise ParserError(e, filename)
breathe.parser.ParserError: mismatched tag: line 8948, column 8430
The full traceback has been saved in /tmp/sphinx-err-elh4u5iq.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

Understanding the error is hard even with the log file. Grepping on filename is not enough, one has to read it all.

# Sphinx version: 1.7.6
# Python version: 3.6.6 (CPython)
# Docutils version: 0.14 
# Jinja2 version: 2.10
# Last messages:
#   building [mo]: targets for 0 po files that are out of date
#   
#   building [html]: targets for 0 source files that are out of date
#   
#   updating environment:
#   
#   [config changed] 6 added, 0 changed, 0 removed
#   
#   reading sources... [ 16%] api-s4u
#   
# Loaded extensions:
#   alabaster (0.7.8) from /usr/lib/python3/dist-packages/alabaster/__init__.py
#   sphinx.ext.mathjax (1.7.6) from /usr/lib/python3/dist-packages/sphinx/ext/mathjax.py
#   breathe (4.9.1) from /usr/lib/python3/dist-packages/breathe/__init__.py
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/breathe/parser/__init__.py", line 81, in parse
    return self.cache[filename]
KeyError: '/home/mquinson/Code/simgrid/docs/source/../../doc/xml/options.xml'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/breathe/parser/compound.py", line 1067, in parse
    doc = minidom.parse(inFilename)
  File "/usr/lib/python3.6/xml/dom/minidom.py", line 1958, in parse
    return expatbuilder.parse(file)
  File "/usr/lib/python3.6/xml/dom/expatbuilder.py", line 911, in parse
    result = builder.parseFile(fp)
  File "/usr/lib/python3.6/xml/dom/expatbuilder.py", line 207, in parseFile
    parser.Parse(buffer, 0)
xml.parsers.expat.ExpatError: mismatched tag: line 8948, column 8430

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/breathe/parser/__init__.py", line 86, in parse
    result = compound.parse(filename)
  File "/usr/lib/python3/dist-packages/breathe/parser/compound.py", line 1071, in parse
    raise ParseError(e)
breathe.parser.compound.ParseError: mismatched tag: line 8948, column 8430

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/cmdline.py", line 304, in main
    app.build(args.force_all, filenames)
  File "/usr/lib/python3/dist-packages/sphinx/application.py", line 331, in build
    self.builder.build_update()
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 342, in build_update
    'out of date' % len(to_build))
  File "/usr/lib/python3/dist-packages/sphinx/builders/__init__.py", line 355, in build
    updated_docnames = set(self.env.update(self.config, self.srcdir, self.doctreedir))
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 565, in update
    self._read_serial(docnames, self.app)
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 584, in _read_serial
    self.read_doc(docname, app)
  File "/usr/lib/python3/dist-packages/sphinx/environment/__init__.py", line 659, in read_doc
    doctree = read_doc(self.app, self, self.doc2path(docname))
  File "/usr/lib/python3/dist-packages/sphinx/io.py", line 302, in read_doc
    pub.publish()
  File "/usr/lib/python3/dist-packages/docutils/core.py", line 217, in publish
    self.settings)
  File "/usr/lib/python3/dist-packages/docutils/readers/__init__.py", line 72, in read
    self.parse()
  File "/usr/lib/python3/dist-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python3/dist-packages/sphinx/parsers.py", line 85, in parse
    self.statemachine.run(inputstring, document, inliner=self.inliner)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 172, in run
    input_source=document['source'])
  File "/usr/lib/python3/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/lib/python3/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 2754, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 328, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 396, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 283, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 197, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python3/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/lib/python3/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 2327, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 2339, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 2082, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/python3/dist-packages/docutils/parsers/rst/states.py", line 2131, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python3/dist-packages/breathe/directives.py", line 298, in run
    finder.filter_(finder_filter, matches)
  File "/usr/lib/python3/dist-packages/breathe/finder/core.py", line 71, in filter_
    item_finder.filter_([FakeParentNode()], filter_, matches)
  File "/usr/lib/python3/dist-packages/breathe/finder/index.py", line 17, in filter_
    compound_finder.filter_(node_stack, filter_, matches)
  File "/usr/lib/python3/dist-packages/breathe/finder/index.py", line 64, in filter_
    file_data = self.compound_parser.parse(self.data_object.refid)
  File "/usr/lib/python3/dist-packages/breathe/parser/__init__.py", line 90, in parse
    raise ParserError(e, filename)
breathe.parser.ParserError: mismatched tag: line 8948, column 8430

Thanks for this great tool anyway. I was waiting for it since ages.

[vermeeren]

Would changing the message of ParserError to the below be an acceptable solution?

breathe.parser.ParserError: file /home/melvin/dev/template/c/build/tmp/doc/doxygen/xml/subtract_8h.xml: mismatched tag: line 34, column 34

Edit: Doxygen 1.8.14 does not generate invalid XML and even emits a warning when the comment in source code is <b>no close tag. I had to manually change output XML to reproduce the ParserError.

[mquinson]

I'm on Doxygen 1.8.13, so this may be the reason. Or maybe this is because the invalid chunk was in an itemize, I'm not sure.

Anyway. If the error message that you propose is what gets printed in the console, that would be perfect: I would not even have to dig into the log file.

Thanks for your responsiveness.

[vermeeren]

released v4.10.0 which fixes this