librelist archives

« back to archive

Importing \file from doxygen

Importing \file from doxygen

From:
Ross, Alasdair
Date:
2012-08-29 @ 20:30
Hi,

  We've just begun to use Sphinx to document a new project I'm working on.
We wanted a way to include our doxygen comments in the Sphinx docs and I 
stumbled across breathe.  It looks like it's going to be very useful for 
us.

  Is there any way to import the \file (and corresponding \brief and 
\author) from a C source file?  We'd like to ensure that we're not 
duplicating descriptions of functionality by having the Sphinx rst doc use
the same high level description as exists in the code.

  Before I'd correctly read the docs I thought doxygenfile might have been
the answer but that does something else (and also breaks - the traceback 
is at the end of the email if it's useful).

  Many thanks for any help/advice you can provide,
-Alasdair





# Sphinx version: 1.1.3
# Python version: 2.6.6
# Docutils version: 0.8.1 release
# Jinja2 version: 2.6
Traceback (most recent call last):
  File "/usr/lib/python2.6/site-packages/sphinx/cmdline.py", line 189, in main
    app.build(force_all, filenames)
  File "/usr/lib/python2.6/site-packages/sphinx/application.py", line 204,
in build
    self.builder.build_update()
  File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", 
line 196, in build_update
    'out of date' % len(to_build))
  File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", 
line 216, in build
    purple, length):
  File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", 
line 120, in status_iterator
    for item in iterable:
  File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line 613,
in update_generator
    self.read_doc(docname, app=app)
  File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line 761,
in read_doc
    pub.publish()
  File "/usr/lib/python2.6/site-packages/docutils/core.py", line 211, in publish
    self.settings)
  File "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", 
line 69, in read
    self.parse()
  File "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", 
line 75, in parse
    self.parser.parse(self.input, document)
  File 
"/usr/lib/python2.6/site-packages/docutils/parsers/rst/__init__.py", line 
157, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 170, in run
    input_source=document['source'])
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
237, in run
    context, state, transitions)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
458, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2943, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 329, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 398, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 284, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
237, in run
    context, state, transitions)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
458, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2709, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 329, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 398, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 284, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
237, in run
    context, state, transitions)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
458, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2709, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 329, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 398, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 284, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
237, in run
    context, state, transitions)
  File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line 
458, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2283, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2295, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2036, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py", 
line 2087, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python2.6/site-packages/breathe/__init__.py", line 253, in run
    finder.filter_(finder_filter, matches)
  File "/usr/lib/python2.6/site-packages/breathe/finder/__init__.py", line
27, in filter_
    item_finder.filter_(filter_, matches)
 File "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py", 
line 27, in filter_
    compound_finder.filter_(self.data_object, filter_, matches)
  File "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
line 70, in filter_
    file_data = self.compound_parser.parse(self.data_object.refid)
  File "/usr/lib/python2.6/site-packages/breathe/parser/__init__.py", line
54, in parse
    result = breathe.parser.doxygen.compound.parse(filename)
  File 
"/usr/lib/python2.6/site-packages/breathe/parser/doxygen/compound.py", 
line 857, in parse
    doc = minidom.parse(inFilename)
  File "/usr/lib64/python2.6/xml/dom/minidom.py", line 1918, in parse
    return expatbuilder.parse(file)
  File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 924, in parse
    result = builder.parseFile(fp)
  File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 207, in parseFile
    parser.Parse(buffer, 0)
ExpatError: not well-formed (invalid token): line 80, column 633

Re: [breathe] Importing \file from doxygen

From:
Michael Jones
Date:
2012-09-02 @ 02:57
Hi Alasdair,

Thanks for the email and for trying Breathe.

I don't think Breathe supports that at the moment though it might not
be too hard to add.  How do you think you would use it?  I think it
could be added to the doxygenfile output.  I feel that is the only
directive which is concerned with the concept of files.  The others
deal more with programming components (classes, functions, etc.)  If
you could provide some idea of where you would expect it to appear in
the output, I would be happy to chase up the implementation side of
things.

Thank you for the stacktrace.  From the looks of it, it seems that the
Expat XML parser is having trouble with the content of the XML output
from Doxygen.  I feel I have encountered issues in the past where
Unicode characters in comments & code cause confusion, though I think
if everything is in the right encoding both doxygen and breathe will
behave themselves.  I'm a little blurry on it though.

Cheers,
Michael


On Thu, Aug 30, 2012 at 8:30 AM, Ross, Alasdair
<Alasdair.Ross@experian.com> wrote:
> Hi,
>
>
>
>   We’ve just begun to use Sphinx to document a new project I’m working on.
> We wanted a way to include our doxygen comments in the Sphinx docs and I
> stumbled across breathe.  It looks like it’s going to be very useful for us.
>
>
>
>   Is there any way to import the \file (and corresponding \brief and
> \author) from a C source file?  We’d like to ensure that we’re not
> duplicating descriptions of functionality by having the Sphinx rst doc use
> the same high level description as exists in the code.
>
>
>
>   Before I’d correctly read the docs I thought doxygenfile might have been
> the answer but that does something else (and also breaks - the traceback is
> at the end of the email if it’s useful).
>
>
>
>   Many thanks for any help/advice you can provide,
>
> -Alasdair
>
>
>
>
>
>
>
>
>
>
>
> # Sphinx version: 1.1.3
>
> # Python version: 2.6.6
>
> # Docutils version: 0.8.1 release
>
> # Jinja2 version: 2.6
>
> Traceback (most recent call last):
>
>   File "/usr/lib/python2.6/site-packages/sphinx/cmdline.py", line 189, in
> main
>
>     app.build(force_all, filenames)
>
>   File "/usr/lib/python2.6/site-packages/sphinx/application.py", line 204,
> in build
>
>     self.builder.build_update()
>
>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", line
> 196, in build_update
>
>     'out of date' % len(to_build))
>
>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", line
> 216, in build
>
>     purple, length):
>
>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", line
> 120, in status_iterator
>
>     for item in iterable:
>
>   File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line 613,
> in update_generator
>
>     self.read_doc(docname, app=app)
>
>   File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line 761,
> in read_doc
>
>     pub.publish()
>
>   File "/usr/lib/python2.6/site-packages/docutils/core.py", line 211, in
> publish
>
>     self.settings)
>
>   File "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", line
> 69, in read
>
>     self.parse()
>
>   File "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", line
> 75, in parse
>
>     self.parser.parse(self.input, document)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/__init__.py",
> line 157, in parse
>
>     self.statemachine.run(inputlines, document, inliner=self.inliner)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 170, in run
>
>     input_source=document['source'])
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 458, in check_line
>
>     return method(match, context, next_state)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2943, in text
>
>     self.section(title.lstrip(), source, style, lineno + 1, messages)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 329, in section
>
>     self.new_subsection(title, lineno, messages)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 398, in new_subsection
>
>     node=section_node, match_titles=1)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 284, in nested_parse
>
>     node=node, match_titles=match_titles)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 195, in run
>
>     results = StateMachineWS.run(self, input_lines, input_offset)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 458, in check_line
>
>     return method(match, context, next_state)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2709, in underline
>
>     self.section(title, source, style, lineno - 1, messages)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 329, in section
>
>     self.new_subsection(title, lineno, messages)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 398, in new_subsection
>
>     node=section_node, match_titles=1)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 284, in nested_parse
>
>     node=node, match_titles=match_titles)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 195, in run
>
>     results = StateMachineWS.run(self, input_lines, input_offset)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 458, in check_line
>
>     return method(match, context, next_state)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2709, in underline
>
>     self.section(title, source, style, lineno - 1, messages)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 329, in section
>
>     self.new_subsection(title, lineno, messages)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 398, in new_subsection
>
>     node=section_node, match_titles=1)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 284, in nested_parse
>
>     node=node, match_titles=match_titles)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 195, in run
>
>     results = StateMachineWS.run(self, input_lines, input_offset)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", line
> 458, in check_line
>
>     return method(match, context, next_state)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2283, in explicit_markup
>
>     nodelist, blank_finish = self.explicit_construct(match)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2295, in explicit_construct
>
>     return method(self, expmatch)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2036, in directive
>
>     directive_class, match, type_name, option_presets)
>
>   File "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2087, in run_directive
>
>     result = directive_instance.run()
>
>   File "/usr/lib/python2.6/site-packages/breathe/__init__.py", line 253, in
> run
>
>     finder.filter_(finder_filter, matches)
>
>   File "/usr/lib/python2.6/site-packages/breathe/finder/__init__.py", line
> 27, in filter_
>
>     item_finder.filter_(filter_, matches)
>
>  File "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
> line 27, in filter_
>
>     compound_finder.filter_(self.data_object, filter_, matches)
>
>   File "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
> line 70, in filter_
>
>     file_data = self.compound_parser.parse(self.data_object.refid)
>
>   File "/usr/lib/python2.6/site-packages/breathe/parser/__init__.py", line
> 54, in parse
>
>     result = breathe.parser.doxygen.compound.parse(filename)
>
>   File
> "/usr/lib/python2.6/site-packages/breathe/parser/doxygen/compound.py", line
> 857, in parse
>
>     doc = minidom.parse(inFilename)
>
>   File "/usr/lib64/python2.6/xml/dom/minidom.py", line 1918, in parse
>
>     return expatbuilder.parse(file)
>
>   File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 924, in parse
>
>     result = builder.parseFile(fp)
>
>   File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 207, in
> parseFile
>
>     parser.Parse(buffer, 0)
>
> ExpatError: not well-formed (invalid token): line 80, column 633

Re: [breathe] Importing \file from doxygen

From:
Ross, Alasdair
Date:
2012-09-14 @ 20:48
Hi Michael,

  Apologies for the delay (end of sprint == bit of a rush).  We upgraded 
our version of doxygen which appears to have solved the stacktrace issue.
  After further investigation it looks like we can use the "doxygengroups"
function to extract the bits we're after.  We want to be able to provide a
general overview of the source at the top of the file and include that in 
our sphinx (thus ensuring we keep everything up to date in one place).
  I'll let you know if our requirements change and hopefully we'll be able
to contribute any changes we need (though we're not really a python shop).

  Cheers,
-Alasdair

-----Original Message-----
From: breathe@librelist.com [mailto:breathe@librelist.com] On Behalf Of 
Michael Jones
Sent: Saturday, September 01, 2012 10:58 PM
To: breathe@librelist.com
Subject: Re: [breathe] Importing \file from doxygen

Hi Alasdair,

Thanks for the email and for trying Breathe.

I don't think Breathe supports that at the moment though it might not be 
too hard to add.  How do you think you would use it?  I think it could be 
added to the doxygenfile output.  I feel that is the only directive which 
is concerned with the concept of files.  The others deal more with 
programming components (classes, functions, etc.)  If you could provide 
some idea of where you would expect it to appear in the output, I would be
happy to chase up the implementation side of things.

Thank you for the stacktrace.  From the looks of it, it seems that the 
Expat XML parser is having trouble with the content of the XML output from
Doxygen.  I feel I have encountered issues in the past where Unicode 
characters in comments & code cause confusion, though I think if 
everything is in the right encoding both doxygen and breathe will behave 
themselves.  I'm a little blurry on it though.

Cheers,
Michael


On Thu, Aug 30, 2012 at 8:30 AM, Ross, Alasdair 
<Alasdair.Ross@experian.com> wrote:
> Hi,
>
>
>
>   We’ve just begun to use Sphinx to document a new project I’m working on.
> We wanted a way to include our doxygen comments in the Sphinx docs and 
> I stumbled across breathe.  It looks like it’s going to be very useful for us.
>
>
>
>   Is there any way to import the \file (and corresponding \brief and
> \author) from a C source file?  We’d like to ensure that we’re not 
> duplicating descriptions of functionality by having the Sphinx rst doc 
> use the same high level description as exists in the code.
>
>
>
>   Before I’d correctly read the docs I thought doxygenfile might have 
> been the answer but that does something else (and also breaks - the 
> traceback is at the end of the email if it’s useful).
>
>
>
>   Many thanks for any help/advice you can provide,
>
> -Alasdair
>
>
>
>
>
>
>
>
>
>
>
> # Sphinx version: 1.1.3
>
> # Python version: 2.6.6
>
> # Docutils version: 0.8.1 release
>
> # Jinja2 version: 2.6
>
> Traceback (most recent call last):
>
>   File "/usr/lib/python2.6/site-packages/sphinx/cmdline.py", line 189, 
> in main
>
>     app.build(force_all, filenames)
>
>   File "/usr/lib/python2.6/site-packages/sphinx/application.py", line 
> 204, in build
>
>     self.builder.build_update()
>
>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", 
> line 196, in build_update
>
>     'out of date' % len(to_build))
>
>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", 
> line 216, in build
>
>     purple, length):
>
>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py", 
> line 120, in status_iterator
>
>     for item in iterable:
>
>   File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line 
> 613, in update_generator
>
>     self.read_doc(docname, app=app)
>
>   File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line 
> 761, in read_doc
>
>     pub.publish()
>
>   File "/usr/lib/python2.6/site-packages/docutils/core.py", line 211, 
> in publish
>
>     self.settings)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", line 
> 69, in read
>
>     self.parse()
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", line 
> 75, in parse
>
>     self.parser.parse(self.input, document)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/__init__.py",
> line 157, in parse
>
>     self.statemachine.run(inputlines, document, inliner=self.inliner)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 170, in run
>
>     input_source=document['source'])
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 458, in check_line
>
>     return method(match, context, next_state)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2943, in text
>
>     self.section(title.lstrip(), source, style, lineno + 1, messages)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 329, in section
>
>     self.new_subsection(title, lineno, messages)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 398, in new_subsection
>
>     node=section_node, match_titles=1)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 284, in nested_parse
>
>     node=node, match_titles=match_titles)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 195, in run
>
>     results = StateMachineWS.run(self, input_lines, input_offset)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 458, in check_line
>
>     return method(match, context, next_state)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2709, in underline
>
>     self.section(title, source, style, lineno - 1, messages)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 329, in section
>
>     self.new_subsection(title, lineno, messages)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 398, in new_subsection
>
>     node=section_node, match_titles=1)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 284, in nested_parse
>
>     node=node, match_titles=match_titles)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 195, in run
>
>     results = StateMachineWS.run(self, input_lines, input_offset)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 458, in check_line
>
>     return method(match, context, next_state)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2709, in underline
>
>     self.section(title, source, style, lineno - 1, messages)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 329, in section
>
>     self.new_subsection(title, lineno, messages)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 398, in new_subsection
>
>     node=section_node, match_titles=1)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 284, in nested_parse
>
>     node=node, match_titles=match_titles)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 195, in run
>
>     results = StateMachineWS.run(self, input_lines, input_offset)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 237, in run
>
>     context, state, transitions)
>
>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py", 
> line 458, in check_line
>
>     return method(match, context, next_state)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2283, in explicit_markup
>
>     nodelist, blank_finish = self.explicit_construct(match)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2295, in explicit_construct
>
>     return method(self, expmatch)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2036, in directive
>
>     directive_class, match, type_name, option_presets)
>
>   File 
> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
> line 2087, in run_directive
>
>     result = directive_instance.run()
>
>   File "/usr/lib/python2.6/site-packages/breathe/__init__.py", line 
> 253, in run
>
>     finder.filter_(finder_filter, matches)
>
>   File "/usr/lib/python2.6/site-packages/breathe/finder/__init__.py", 
> line 27, in filter_
>
>     item_finder.filter_(filter_, matches)
>
>  File 
> "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
> line 27, in filter_
>
>     compound_finder.filter_(self.data_object, filter_, matches)
>
>   File 
> "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
> line 70, in filter_
>
>     file_data = self.compound_parser.parse(self.data_object.refid)
>
>   File "/usr/lib/python2.6/site-packages/breathe/parser/__init__.py", 
> line 54, in parse
>
>     result = breathe.parser.doxygen.compound.parse(filename)
>
>   File
> "/usr/lib/python2.6/site-packages/breathe/parser/doxygen/compound.py", 
> line 857, in parse
>
>     doc = minidom.parse(inFilename)
>
>   File "/usr/lib64/python2.6/xml/dom/minidom.py", line 1918, in parse
>
>     return expatbuilder.parse(file)
>
>   File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 924, in 
> parse
>
>     result = builder.parseFile(fp)
>
>   File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 207, in 
> parseFile
>
>     parser.Parse(buffer, 0)
>
> ExpatError: not well-formed (invalid token): line 80, column 633

Re: [breathe] Importing \file from doxygen

From:
Michael Jones
Date:
2012-09-15 @ 05:26
Good to hear, let me know if you have any further thoughts.

More than happy to receive contributions!  Please code away.

Cheers,
Michael

On Sat, Sep 15, 2012 at 8:48 AM, Ross, Alasdair
<Alasdair.Ross@experian.com> wrote:
> Hi Michael,
>
>   Apologies for the delay (end of sprint == bit of a rush).  We upgraded
our version of doxygen which appears to have solved the stacktrace issue.
>   After further investigation it looks like we can use the 
"doxygengroups" function to extract the bits we're after.  We want to be 
able to provide a general overview of the source at the top of the file 
and include that in our sphinx (thus ensuring we keep everything up to 
date in one place).
>   I'll let you know if our requirements change and hopefully we'll be 
able to contribute any changes we need (though we're not really a python 
shop).
>
>   Cheers,
> -Alasdair
>
> -----Original Message-----
> From: breathe@librelist.com [mailto:breathe@librelist.com] On Behalf Of 
Michael Jones
> Sent: Saturday, September 01, 2012 10:58 PM
> To: breathe@librelist.com
> Subject: Re: [breathe] Importing \file from doxygen
>
> Hi Alasdair,
>
> Thanks for the email and for trying Breathe.
>
> I don't think Breathe supports that at the moment though it might not be
too hard to add.  How do you think you would use it?  I think it could be 
added to the doxygenfile output.  I feel that is the only directive which 
is concerned with the concept of files.  The others deal more with 
programming components (classes, functions, etc.)  If you could provide 
some idea of where you would expect it to appear in the output, I would be
happy to chase up the implementation side of things.
>
> Thank you for the stacktrace.  From the looks of it, it seems that the 
Expat XML parser is having trouble with the content of the XML output from
Doxygen.  I feel I have encountered issues in the past where Unicode 
characters in comments & code cause confusion, though I think if 
everything is in the right encoding both doxygen and breathe will behave 
themselves.  I'm a little blurry on it though.
>
> Cheers,
> Michael
>
>
> On Thu, Aug 30, 2012 at 8:30 AM, Ross, Alasdair 
<Alasdair.Ross@experian.com> wrote:
>> Hi,
>>
>>
>>
>>   We’ve just begun to use Sphinx to document a new project I’m working on.
>> We wanted a way to include our doxygen comments in the Sphinx docs and
>> I stumbled across breathe.  It looks like it’s going to be very useful for us.
>>
>>
>>
>>   Is there any way to import the \file (and corresponding \brief and
>> \author) from a C source file?  We’d like to ensure that we’re not
>> duplicating descriptions of functionality by having the Sphinx rst doc
>> use the same high level description as exists in the code.
>>
>>
>>
>>   Before I’d correctly read the docs I thought doxygenfile might have
>> been the answer but that does something else (and also breaks - the
>> traceback is at the end of the email if it’s useful).
>>
>>
>>
>>   Many thanks for any help/advice you can provide,
>>
>> -Alasdair
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> # Sphinx version: 1.1.3
>>
>> # Python version: 2.6.6
>>
>> # Docutils version: 0.8.1 release
>>
>> # Jinja2 version: 2.6
>>
>> Traceback (most recent call last):
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/cmdline.py", line 189,
>> in main
>>
>>     app.build(force_all, filenames)
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/application.py", line
>> 204, in build
>>
>>     self.builder.build_update()
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py",
>> line 196, in build_update
>>
>>     'out of date' % len(to_build))
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py",
>> line 216, in build
>>
>>     purple, length):
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/builders/__init__.py",
>> line 120, in status_iterator
>>
>>     for item in iterable:
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line
>> 613, in update_generator
>>
>>     self.read_doc(docname, app=app)
>>
>>   File "/usr/lib/python2.6/site-packages/sphinx/environment.py", line
>> 761, in read_doc
>>
>>     pub.publish()
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/core.py", line 211,
>> in publish
>>
>>     self.settings)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", line
>> 69, in read
>>
>>     self.parse()
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/readers/__init__.py", line
>> 75, in parse
>>
>>     self.parser.parse(self.input, document)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/__init__.py",
>> line 157, in parse
>>
>>     self.statemachine.run(inputlines, document, inliner=self.inliner)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 170, in run
>>
>>     input_source=document['source'])
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 237, in run
>>
>>     context, state, transitions)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 458, in check_line
>>
>>     return method(match, context, next_state)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2943, in text
>>
>>     self.section(title.lstrip(), source, style, lineno + 1, messages)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 329, in section
>>
>>     self.new_subsection(title, lineno, messages)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 398, in new_subsection
>>
>>     node=section_node, match_titles=1)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 284, in nested_parse
>>
>>     node=node, match_titles=match_titles)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 195, in run
>>
>>     results = StateMachineWS.run(self, input_lines, input_offset)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 237, in run
>>
>>     context, state, transitions)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 458, in check_line
>>
>>     return method(match, context, next_state)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2709, in underline
>>
>>     self.section(title, source, style, lineno - 1, messages)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 329, in section
>>
>>     self.new_subsection(title, lineno, messages)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 398, in new_subsection
>>
>>     node=section_node, match_titles=1)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 284, in nested_parse
>>
>>     node=node, match_titles=match_titles)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 195, in run
>>
>>     results = StateMachineWS.run(self, input_lines, input_offset)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 237, in run
>>
>>     context, state, transitions)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 458, in check_line
>>
>>     return method(match, context, next_state)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2709, in underline
>>
>>     self.section(title, source, style, lineno - 1, messages)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 329, in section
>>
>>     self.new_subsection(title, lineno, messages)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 398, in new_subsection
>>
>>     node=section_node, match_titles=1)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 284, in nested_parse
>>
>>     node=node, match_titles=match_titles)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 195, in run
>>
>>     results = StateMachineWS.run(self, input_lines, input_offset)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 237, in run
>>
>>     context, state, transitions)
>>
>>   File "/usr/lib/python2.6/site-packages/docutils/statemachine.py",
>> line 458, in check_line
>>
>>     return method(match, context, next_state)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2283, in explicit_markup
>>
>>     nodelist, blank_finish = self.explicit_construct(match)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2295, in explicit_construct
>>
>>     return method(self, expmatch)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2036, in directive
>>
>>     directive_class, match, type_name, option_presets)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/docutils/parsers/rst/states.py",
>> line 2087, in run_directive
>>
>>     result = directive_instance.run()
>>
>>   File "/usr/lib/python2.6/site-packages/breathe/__init__.py", line
>> 253, in run
>>
>>     finder.filter_(finder_filter, matches)
>>
>>   File "/usr/lib/python2.6/site-packages/breathe/finder/__init__.py",
>> line 27, in filter_
>>
>>     item_finder.filter_(filter_, matches)
>>
>>  File
>> "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
>> line 27, in filter_
>>
>>     compound_finder.filter_(self.data_object, filter_, matches)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/breathe/finder/doxygen/index.py",
>> line 70, in filter_
>>
>>     file_data = self.compound_parser.parse(self.data_object.refid)
>>
>>   File "/usr/lib/python2.6/site-packages/breathe/parser/__init__.py",
>> line 54, in parse
>>
>>     result = breathe.parser.doxygen.compound.parse(filename)
>>
>>   File
>> "/usr/lib/python2.6/site-packages/breathe/parser/doxygen/compound.py",
>> line 857, in parse
>>
>>     doc = minidom.parse(inFilename)
>>
>>   File "/usr/lib64/python2.6/xml/dom/minidom.py", line 1918, in parse
>>
>>     return expatbuilder.parse(file)
>>
>>   File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 924, in
>> parse
>>
>>     result = builder.parseFile(fp)
>>
>>   File "/usr/lib64/python2.6/xml/dom/expatbuilder.py", line 207, in
>> parseFile
>>
>>     parser.Parse(buffer, 0)
>>
>> ExpatError: not well-formed (invalid token): line 80, column 633