Looks like breathe doesn't know how to deal with \par (or maybe ALIASES) yet.

I have the following ALIASES in my Doxyfile:
ALIASES = "sideeffect=\par Side Effects:\n"

When I try to use "sideeffect", as in
/**
* Foo frob routine.
* @sideeffect Frobs any foos.
*/
void frob_foos(void);

The output is

void frob_foos(void)

    Foo frob routine.

    Par
        Frobs any foos.

Instead of something like
....
Side Effects:
Frobs any foos.

I'm currently using Breathe to document a C/C++ library (libmaple). So far, the usage of Breathe has been pretty limited (64 total Breathe directives through the whole project), and performance has been fine. I recently greatly expanded my usage of breathe, but building the expanded docs takes an unusable amount of time.

It took several minutes to build the documentation for a single C file (which I laid out by hand with ~130 Breathe directives, specifically doxygenstruct, doxygenvariable, doxygenenum, and doxygendefine). With over 1200 such directives now in the finished docs, I estimate it would take hours to build everything.

Using doxygenfile instead brings performance to a satisfactory level, so it seems like Breathe must just be repeating a lot of work by searching through the same parsed XML trees over and over again on each individual directive. Pre-parsing and caching the results seems like the obvious way to speed things up, but I'm not familiar enough with the code base to go about it.

Any help would be extremely appreciated. I am happy to provide any additional details. (For now, I've gone back to using doxygenfile, but the layout it chooses isn't what I'd prefer, and using it takes away the ability to include extra documentation throughout individual pieces of a file's API).

For reference, the complete, slow docs/ tree is available in the libmaple-expanded-docs branch of my libmaple fork here:

https://github.com/mbolivar/libmaple/tree/libmaple-expanded-docs/docs

To make it clearer in case people get confused.

Michael

I'm trying to use breathe as part of the cpp-netlib project and all I have going on there are templates. Has there been any thought put into generating documentation from templates properly? I can use doxygenstruct to reference a template struct, but I don't see it properly described as a template.

Use of the doxygenfunction directive results in a \item outside of an itemize in the LaTeX output which causes any compilation of the generated LaTeX sources (e.g. make pdflatex) to fail. This issue can be replicated in the Breathe testsuite.

I don't have a very precise description of this issue, and unfortunately I haven't been able to come up with any examples smaller than the full project on which I use breathe.

'doxygenfile' seems to be putting the namespace-level documentation from several files into the output for a single file. The kind of documentation I'm talking about is right before the opening namespace in a header file. For example:

#ifndef SOME_INCLUDE_GUARD
#define SOME_INCLUDE_GUARD

#include <secret_nuclear_launch_codes.hpp>

/** THESE ARE THE COMMENTS I'M TALKING ABOUT
  */

namespace foo {
...etc...

I'm seeing that, in some cases, doxygenfile is displaying these namespace-level comments from several files. So, for the file above, breathe will have the expected commentary, but it will also include similar documentation from other files. In the project where I'm seeing this effect, breathe seems to consistently put all namespace-level documentation for my top-level namespace in doxygenfile output.

For a concrete example, you can try building the docs for the project I'm talking about, ackward: http://code.google.com/p/ackward/

The wiki has a link to the docs which describe the build process. If you manage to build it (and it may not be easy), the documentation for "Tuple" under the "ackward::core" API docs shows the problem.

I get that while trying to follow the instruction on the website:
http://michaeljones.github.com/breathe/directives.html

unknown option: "sections".

.. doxygenclass:: ApiModule
   :sections: public*, protected*
   :members:

Hi,

Thanks for your work on breathe. I haven't used it much yet, but I can see how it could come handy.

Anyway, while trying to create an index page (with the doxygenindex directive) for a project, the following traceback was generated:

Exception occurred:
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/index.py", line 13, in render
    nodelist.extend(compound_renderer.render())
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/index.py", line 101, in render
    nodelist.extend(data_renderer.render())
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 9, in render
    nodelist = compound_renderer.render()
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 73, in render
    subnodes = renderer.render()
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 151, in render
    node_list.extend(renderer.render())
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 225, in render
    definition = self.node_factory.paragraph("", "", *self.description())
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 210, in description
    description_nodes.append(self.node_factory.paragraph( "", "", *renderer.render()))
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 412, in render
    nodelist.extend(renderer.render())
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/compound.py", line 829, in render
    renderer = self.renderer_factory.create_renderer(self.data_object, self.data_object.getValue())
  File "/usr/lib/python2.7/dist-packages/breathe/renderer/rst/doxygen/__init__.py", line 115, in create_renderer
    Renderer = self.renderers[node_type]
KeyError: 'docinternal'

I don't know much about breathe's code, so for now I simply replaced the line of code that raised the exception with this one:

        try:
            Renderer = self.renderers[node_type]
        except KeyError:
            return NullRenderer()

This is certainly wrong (there should be proper renderers for the docinternal family of node types), but it allowed me to generate the full index.

Tested on Debian testing with the following versions:
doxygen: 1.8.1.2-2
breathe: 1.0.0
Sphinx: 1.1.3+dfsg-4
docutils: 0.8.1-8

Cheers,
François

Hi,

I have the following typedef:
typedef void (*voidFuncPtr)(void);

At least using HTML output, the result of
.. doxygentypedef:: voidFuncPtr
is malformed. Doing my best in Markdown, it looks like this:

void(* voidFuncPtr

From user dpl in issue 21:

Latex in the original documentation. For example consider a header with an equation like

/*!
*  \brief This class does some math.
*
* It relies on the fact that
* \f$
* f(x)=x^{g-1} \frac{\exp{\left(-v/\theta\right)}}{\Gamma(u)\,\alpha^i}
* \f$
* with one parameter \f$\theta\f$ and another \f$\alpha\f$.
*
*/
class SomeMath : public Math< double >

In such a case the resulting documentation shows simply nothing in place of the equation and parameter symbols. For us, latex docs are pretty important. Also note that there are a couple of different math modes in Doxygen.

How would we reference overloaded member functions? Perhaps it is possible to do this by adding the number of arguments, and a string hint for the type of each argument..

In addition to that, it would really help if we can specify the class name the member function belongs to.

the doxygen return syntax looks something like:

< para >some text < simplesect kind="return" >< para >some more return text< /para >< /simplesect >< /para >

where it embeds into . breathe current ignores this... i'm guessing you would have to add something to the docParaType buildChildren function?

Hi,

I'm testing breathe against a large existing codebase that uses doxygen for the generated docs.
I'm trying to move to reST and Sphinx for the majority of our docs. I followed the steps in the breathe quickstart guide but I ran into the following problem trying to use the doxygenindex directive as the first test of this integration:

%> make html
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.0.3
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] aware-doxy                                                                                                                                
Exception occurred:
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 284, in render
    name = self.lookup[self.data_object.kind]
KeyError: u'templateparam'
The full traceback has been saved in /tmp/sphinx-err-_HxVBJ.log, if you want to report the issue to the developers.

and here's the full error log:

%> cat  /tmp/sphinx-err-_HxVBJ.log
# Sphinx version: 1.0.3
# Docutils version: 0.5 release
# Jinja2 version: 2.5
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/cmdline.py", line 173, in main
    app.build(force_all, filenames)
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/application.py", line 207, in build
    self.builder.build_update()
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/builders/__init__.py", line 198, in build_update
    'out of date' % len(to_build))
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/builders/__init__.py", line 218, in build
    purple, length):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/builders/__init__.py", line 120, in status_iterator
    for item in iterable:
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/environment.py", line 515, in update_generator
    self.read_doc(docname, app=app)
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.0.3-py2.6.egg/sphinx/environment.py", line 655, in read_doc
    pub.publish()
  File "/usr/lib/python2.6/dist-packages/docutils/core.py", line 204, in publish
    self.settings)
  File "/usr/lib/python2.6/dist-packages/docutils/readers/__init__.py", line 69, in read
    self.parse()
  File "/usr/lib/python2.6/dist-packages/docutils/readers/__init__.py", line 75, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/__init__.py", line 157, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/usr/lib/python2.6/dist-packages/docutils/statemachine.py", line 232, in run
    context, state, transitions)
  File "/usr/lib/python2.6/dist-packages/docutils/statemachine.py", line 420, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2883, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 308, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 376, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 266, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.6/dist-packages/docutils/statemachine.py", line 232, in run
    context, state, transitions)
  File "/usr/lib/python2.6/dist-packages/docutils/statemachine.py", line 420, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2239, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2251, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 1994, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2043, in run_directive
    result = directive_instance.run()
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/__init__.py", line 54, in run
    nodes = builder.build(data_object)
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/builder.py", line 17, in build
    return object_renderer.render()
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/index.py", line 13, in render
    nodelist.extend(compound_renderer.render())
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/index.py", line 53, in render
    nodelist.extend(data_renderer.render())
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 9, in render
    return compound_renderer.render()
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 69, in render
    subnodes = renderer.render()
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 100, in render
    defs.extend(renderer.render())
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 146, in render
    description_nodes.append(self.node_factory.paragraph( "", "", *renderer.render()))
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 174, in render
    nodelist.extend(renderer.render())
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 364, in render
    return renderer.render()
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 254, in render
    nodelist.extend(renderer.render())
  File "/home/josh/sandbox/svn/gni/aware/trunk/code/doc/examples/baseExamples/doc/sphinx/breathe/renderer/rst/doxygen/compound.py", line 284, in render
    name = self.lookup[self.data_object.kind]
KeyError: u'templateparam'

Please let me know if you need more info.

Thanks!

Josh

If a code base has more than one file with the same name, there does not appear to be any way to tell the doxygenfile directive which to choose. (If there is a way to do this, then it's not very apparent.)

For example, suppose I've got a project structure like this:

src/
  myproj/
    subproj1/
      Util.hpp
    subproj2/
      Util.hpp

and I use this in my sphinx docs:

.. doxygenfile:: Util.hpp

In this case, breathe seems to pick one of the Util.hpp files without complaint. But I can't find a way to tell it which to choose.

If there's a way to do this already, then perhaps this is just a documentation enhancement.

How would we reference overloaded member functions? Perhaps it is possible to do this by adding the number of arguments, and a string hint for the type of each argument..

In addition to that, it would really help if we can specify the class name the member function belongs to.

patrick@vercors:~/projects/projects_sphinx/breathe/breathe/testsuite$ make html
mkdir -p build/html build/doctrees
sphinx-build -b html -a -d build/doctrees source build/html
Running Sphinx v1.0b1
loading pickled environment... not yet created
building [html]: all source files
updating environment: 11 added, 0 changed, 0 removed
reading sources... [ 90%] source/tinyxml
Exception occurred:
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2070, in run_directive
'Directive "%s" must return a list of nodes.' % type_name
AssertionError: Directive "doxygenindex" must return a list of nodes.

Sphinx version: 1.0b1

Docutils version: 0.6 release

Jinja2 version: 2.4.1

Traceback (most recent call last):
File "/usr/local/lib/python2.6/dist-packages/sphinx/cmdline.py", line 173, in main
app.build(force_all, filenames)
File "/usr/local/lib/python2.6/dist-packages/sphinx/application.py", line 201, in build
self.builder.build_all()
File "/usr/local/lib/python2.6/dist-packages/sphinx/builders/init.py", line 161, in build_all
self.build(None, summary='all source files', method='all')
File "/usr/local/lib/python2.6/dist-packages/sphinx/builders/init.py", line 218, in build
purple, length):
File "/usr/local/lib/python2.6/dist-packages/sphinx/builders/init.py", line 120, in status_iterator
for item in iterable:
File "/usr/local/lib/python2.6/dist-packages/sphinx/environment.py", line 502, in update_generator
self.read_doc(docname, app=app)
File "/usr/local/lib/python2.6/dist-packages/sphinx/environment.py", line 642, in read_doc
pub.publish()
File "/usr/local/lib/python2.6/dist-packages/docutils/core.py", line 203, in publish
self.settings)
File "/usr/local/lib/python2.6/dist-packages/docutils/readers/init.py", line 69, in read
self.parse()
File "/usr/local/lib/python2.6/dist-packages/docutils/readers/init.py", line 75, in parse
self.parser.parse(self.input, document)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/init.py", line 157, in parse
self.statemachine.run(inputlines, document, inliner=self.inliner)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 170, in run
input_source=document['source'])
File "/usr/local/lib/python2.6/dist-packages/docutils/statemachine.py", line 233, in run
context, state, transitions)
File "/usr/local/lib/python2.6/dist-packages/docutils/statemachine.py", line 421, in check_line
return method(match, context, next_state)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2678, in underline
self.section(title, source, style, lineno - 1, messages)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 323, in section
self.new_subsection(title, lineno, messages)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
node=section_node, match_titles=1)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 278, in nested_parse
node=node, match_titles=match_titles)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 195, in run
results = StateMachineWS.run(self, input_lines, input_offset)
File "/usr/local/lib/python2.6/dist-packages/docutils/statemachine.py", line 233, in run
context, state, transitions)
File "/usr/local/lib/python2.6/dist-packages/docutils/statemachine.py", line 421, in check_line
return method(match, context, next_state)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2258, in explicit_markup
nodelist, blank_finish = self.explicit_construct(match)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2270, in explicit_construct
return method(self, expmatch)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2013, in directive
directive_class, match, type_name, option_presets)
File "/usr/local/lib/python2.6/dist-packages/docutils/parsers/rst/states.py", line 2070, in run_directive
'Directive "%s" must return a list of nodes.' % type_name
AssertionError: Directive "doxygenindex" must return a list of nodes.

Instead of requiring breathe_default_project as well (which I think you do at the moment.)

When I try to use breathe, I get following error:

Exception occurred:
File "/usr/lib/pymodules/python2.5/docutils/nodes.py", line 537, in getitem
return self.attributes[key]
KeyError: 'refdoc'

Hi Micheal,

first of all thanks for the idea of breathe -- i think it will fill quite an important gap in the future.
We are currently running some tests to see if we can port all doxygen and some custom documentation for a multi-10k-line c++ project to sphinx.

Sadly, I already have problems with the testsuite and pasted the output below. Most likely, it may be due to software versions: I have both python3 and python2, where in arch linux python3 is named python:

> python --version
Python 3.1.3 
> python2 --version
Python 2.7.1
> pacman -Qi docutils
Name           : docutils
Version        : 0.7-5
> sphinx-build
Sphinx v1.0.7
> doxygen --version
1.7.2

below is the output which throws me at the pdb console. do you have any idea what i could do to mitigate, or which of the software i should try downgrading first? unfortunately, i am not so familiar with all things python-ish.

Thanks for any pointers! -Paul
Edit: P.S.: A one-page regular sphinx build using a local
sphinx-quickstart project runs just fine though.

(user@host): /home/user/bin/breathe/testsuite $
 > make clean
rm -rf build/*
 > ls -a *
Makefile  pseudorst.py
build:
.  ..  doctrees  html
source:
.   class.rst      conf.py       credits.rst     domains.rst  embeddedrst.rst  function.rst  inline.rst   nutshell.h      specific.rst  struct.rst     tinyxml.rst
..  codeguide.rst  contributing.rst  directives.rst  doxygen.rst  enum.rst     index.rst     members.rst  quickstart.rst  _static       testpages.rst  typedef.rst

 > make html
mkdir -p build/html build/doctrees
sphinx-build -b html -P -a -d build/doctrees   source build/html
Running Sphinx v1.0.7
loading pickled environment... not yet created
building [html]: all source files
updating environment: 19 added, 0 changed, 0 removed
Exception occurred while building, starting debugger:                                                                                                                            
Traceback (most recent call last):
  File "/usr/lib/python2.7/site-packages/sphinx/cmdline.py", line 188, in main
    app.build(force_all, filenames)
  File "/usr/lib/python2.7/site-packages/sphinx/application.py", line 203, in build
    self.builder.build_all()
  File "/usr/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 161, in build_all
    self.build(None, summary='all source files', method='all')
  File "/usr/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 218, in build
    purple, length):
  File "/usr/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 120, in status_iterator
    for item in iterable:
  File "/usr/lib/python2.7/site-packages/sphinx/environment.py", line 519, in update_generator
    self.read_doc(docname, app=app)
  File "/usr/lib/python2.7/site-packages/sphinx/environment.py", line 664, in read_doc
    pub.publish()
  File "/usr/lib/python2.7/site-packages/docutils/core.py", line 203, in publish
    self.settings)
  File "/usr/lib/python2.7/site-packages/docutils/readers/__init__.py", line 69, in read
    self.parse()
  File "/usr/lib/python2.7/site-packages/docutils/readers/__init__.py", line 75, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/__init__.py", line 157, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/usr/lib/python2.7/site-packages/docutils/statemachine.py", line 233, in run
    context, state, transitions)
  File "/usr/lib/python2.7/site-packages/docutils/statemachine.py", line 454, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 2706, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 329, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 398, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 284, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.7/site-packages/docutils/statemachine.py", line 233, in run
    context, state, transitions)
  File "/usr/lib/python2.7/site-packages/docutils/statemachine.py", line 454, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 2706, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 329, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 398, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 284, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.7/site-packages/docutils/statemachine.py", line 233, in run
    context, state, transitions)
  File "/usr/lib/python2.7/site-packages/docutils/statemachine.py", line 454, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 2281, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 2293, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 2035, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/python2.7/site-packages/docutils/parsers/rst/states.py", line 2086, in run_directive
    result = directive_instance.run()
  File "../breathe/__init__.py", line 157, in run
    finder = self.finder_factory.create_finder(project_info)
  File "../breathe/finder/__init__.py", line 55, in create_finder
    root = self.parser.parse(project_info)
  File "../breathe/parser/__init__.py", line 22, in parse
    raise ParserError(filename)
ParserError: ../examples/doxygen/class/xml/index.xml
> /home/user/bin/breathe/breathe/parser/__init__.py(22)parse()
-> raise ParserError(filename)
(Pdb) Traceback (most recent call last):
  File "/usr/bin/sphinx-build", line 9, in <module>
    load_entry_point('Sphinx==1.0.7', 'console_scripts', 'sphinx-build')()
  File "/usr/lib/python2.7/site-packages/sphinx/__init__.py", line 67, in main
    return cmdline.main(argv)
  File "/usr/lib/python2.7/site-packages/sphinx/cmdline.py", line 204, in main
    pdb.post_mortem(sys.exc_info()[2])
  File "/usr/lib/python2.7/pdb.py", line 1267, in post_mortem
    p.interaction(None, t)
  File "/usr/lib/python2.7/pdb.py", line 210, in interaction
    self.cmdloop()
  File "/usr/lib/python2.7/cmd.py", line 130, in cmdloop
    line = raw_input(self.prompt)
KeyboardInterrupt
make: *** [html] Error 1

Makes it more readily available for those who would like to try it. Takes a bit of prep work, but nothing too much. The sphinx-to-github repos has an example of the necessary setup thanks to KennethReitz.

If I try to execute two sphinx in parallel, breathe seems to fail on stealing itself temporary file. It sounds like unsafe using of temporary files.

Full traceback:

# Sphinx version: 1.0.5
# Python version: 2.5.5
# Docutils version: 0.7 release
# Jinja2 version: 2.5.5
Traceback (most recent call last):
  File "/usr/lib/pymodules/python2.5/sphinx/cmdline.py", line 173, in main
    app.build(force_all, filenames)
  File "/usr/lib/pymodules/python2.5/sphinx/application.py", line 207, in build
    self.builder.build_update()
  File "/usr/lib/pymodules/python2.5/sphinx/builders/__init__.py", line 198, in build_update
    'out of date' % len(to_build))
  File "/usr/lib/pymodules/python2.5/sphinx/builders/__init__.py", line 218, in build
    purple, length):
  File "/usr/lib/pymodules/python2.5/sphinx/builders/__init__.py", line 120, in status_iterator
    for item in iterable:
  File "/usr/lib/pymodules/python2.5/sphinx/environment.py", line 511, in update_generator
    self.read_doc(docname, app=app)
  File "/usr/lib/pymodules/python2.5/sphinx/environment.py", line 651, in read_doc
    pub.publish()
  File "/usr/lib/pymodules/python2.5/docutils/core.py", line 203, in publish
    self.settings)
  File "/usr/lib/pymodules/python2.5/docutils/readers/__init__.py", line 69, in read
    self.parse()
  File "/usr/lib/pymodules/python2.5/docutils/readers/__init__.py", line 75, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/__init__.py", line 157, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/usr/lib/pymodules/python2.5/docutils/statemachine.py", line 233, in run
    context, state, transitions)
  File "/usr/lib/pymodules/python2.5/docutils/statemachine.py", line 454, in check_line
    return method(match, context, next_state)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2706, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 329, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 398, in new_subsection
    node=section_node, match_titles=1)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 284, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/pymodules/python2.5/docutils/statemachine.py", line 233, in run
    context, state, transitions)
  File "/usr/lib/pymodules/python2.5/docutils/statemachine.py", line 454, in check_line
    return method(match, context, next_state)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2283, in explicit_markup
    self.explicit_list(blank_finish)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2314, in explicit_list
    match_titles=self.state_machine.match_titles)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 321, in nested_list_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/pymodules/python2.5/docutils/statemachine.py", line 233, in run
    context, state, transitions)
  File "/usr/lib/pymodules/python2.5/docutils/statemachine.py", line 454, in check_line
    return method(match, context, next_state)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2587, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2293, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2035, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/pymodules/python2.5/docutils/parsers/rst/states.py", line 2086, in run_directive
    result = directive_instance.run()
  File "/home/mcihar/private/gammu/external/breathe/breathe/__init__.py", line 108, in run
    finder = self.finder_factory.create_finder(project_info)
  File "/home/mcihar/private/gammu/external/breathe/breathe/finder/__init__.py", line 55, in create_finder
    root = self.parser.parse(project_info)
  File "/home/mcihar/private/gammu/external/breathe/breathe/parser/__init__.py", line 20, in parse
    return breathe.parser.doxygen.index.parse(filename)
  File "/home/mcihar/private/gammu/external/breathe/breathe/parser/doxygen/index.py", line 43, in parse
    doc = minidom.parse(inFilename)
  File "/usr/lib/python2.5/xml/dom/minidom.py", line 1915, in parse
    return expatbuilder.parse(file)
  File "/usr/lib/python2.5/xml/dom/expatbuilder.py", line 924, in parse
    result = builder.parseFile(fp)
  File "/usr/lib/python2.5/xml/dom/expatbuilder.py", line 211, in parseFile
    parser.Parse("", True)
ExpatError: no element found: line 2256, column 2

Need some way to note that a particular piece of output from breathe should not contain any destination linking information.

The aim being to allow you to reference the same information from different parts of your documentation without Sphinx complaining about multiple references/ids.

By email:

It would be really interesting if we could embed reST constructs inside class/function detailed descriptions. Looks like doxygen preserves xml tags inside comment blocks so breathe might be able to parse something like

/**
   My own class makes fancy computations such as
   <rest>
   .. math::

       a(u, v) = \int \nabla u \cdot \nabla v \; \rm{d}\Omega  
   </rest>
*/

and do the appropriate rendering. Do you think such a feature would be easily implemented?

Hi.

Good job for your great tool.

Just a side note: the official name is one word reStructuredText (not Restructured text)

Following the quickstart steps I got a error that end with

  File "/usr/lib/python3.3/site-packages/breathe/directives.py", line 664, in default_path
    return self.projects[self.default_project]
KeyError: ''

To solve this erro I only add the breathe_default_project in conf.py.

Hi together,

I downloaded your nice project 'breathe', however wanted to use in together with Python 3.2. Therefore I adapted to code, that is now working with python 3.2.

Additionally, I also wanted to display members and functions that are in any protected and private section. Therefore I added an option 'section', where you can give a comma-separated list with section titles, that should be considered (wildcards are allowed).

Are you interested in the python 3 port and/or the section-change? If yes, how can I send it to you or upload it? I'm not really familiar with git, but I think I might be able to do create a diff or something similar.

Cheers
Marc

Hi, I am back after some testing :)

With my setup, ( Python 2.7.1, 0.7-5, Sphinx v1.0.7, doxygen 1.7.2 ), the doxygenclass:: command only seems to process (or output) until the end of the class description (but does not seem to generate errors). For example, this is an exact excerpt of firefox showing breathe/testsuite/build/html/index.html :

And you get something like this:

    class Nutshell

        An overly extended example of how to use breathe.

        With a little bit of a elaboration, should you feel it necessary.

Sound reasonable? To get started, go checkout the quickstart guide.

Evidently, this differs from the version you have online: all members are missing. The same is for classes in our project, or if I give the doxygenclass:: nutshell command in my own test documentation. For doxygenindex:: however, the nutshell documentation looks almost identical to your version online, only that the parameter documentation is on a new line now. Yet still, for me Doxygenclass would probably be most useful, as Doxygen itself structures its html pages in a class-oriented way and doxygenindex:: can lead to overkill. Tell me if I can help debugging this.
Oh, and the html looks like this:

    <blockquote>
    <div><p id="minimalclass_nutshell"><em>class</em> <strong>Nutshell</strong></p>
    <blockquote>
    <div><p>
    <p>An overly extended example of how to use breathe. </p>
        </p>
    <p>
    <p>With a little bit of a elaboration, should you feel it necessary. </p>
        </p>
    </div></blockquote>
    </div></blockquote>
    </div>
    </div>

This reported, let me list some other impressions I had. Let me know if any of these should be edited into a new issue:

• Latex in the original documentation. For example consider a header with an equation like
  /*!
  * \brief This class does some math.
  *
  * It relies on the fact that
  * \f$
  * f(x)=x^{g-1} \frac{\exp{\left(-v/\theta\right)}}{\Gamma(u),\alpha^i}
  * \f$
  * with one parameter \f$\theta\f$ and another \f$\alpha\f$.
  *
  */
  class SomeMath : public Math< double >
  In such a case the resulting documentation shows simply nothing in place of the equation and parameter symbols. For us, latex docs are pretty important. Also note that there are a couple of different math modes in Doxygen.
• Parser errors. I don't know if these errors are related to breathe or sphinx or volatile coding, but out of our 10 code domains, five do not compile due to some parser errors. I give the five parser errors where each component gets stuck below. Admittadly, the function signatures are non-trivial, and I am happy to send along the full backtrace, xml code, compile minimal examples, make test cases out of them, post to sphinx-dev, or whatever you think is best for these. It is also possible that in the source code, they are even more complex (e.g., inline seems to get scrubbed), thus potentially hiding hints. But I didn't want to run off in any direction prematurely without hearing your opinion.

One:
Exception occurred:
File "/usr/lib/python2.7/site-packages/sphinx/domains/cpp.py", line 458, in fail
(msg, self.pos, self.definition))
DefinitionError: Invalid definition: expected parentheses for function [error at 23]
std::istream& operator>>(std::istream &is, Array< T > &a)
Two:
DefinitionError: Invalid definition: expected name [error at 24]
std::ostream& operator<<(std::ostream &stream, const CMA &cma)
Three:
DefinitionError: Invalid definition: expected name [error at 100]
ComposedFS::ComposedFS(Operator op, const RCPtr< FuzzySet > &f1, const RCPtr< FuzzySet > &f2, double(_userFunction)(double, double))
Four:
DefinitionError: Invalid definition: expected name [error at 79]
void bfgs(Array< double > &p, double gtol, unsigned &iter, double &fret, double(_func)(const Array< double > &), void(*dfunc)(const Array< double > &, Array< double > &), unsigned iterMax=200, LinMinTypes linmintype=DERIVLINMIN)

Five:
DefinitionError: Invalid definition: expected parentheses for function [error at 19]
const unsigned int Model::getInputDimension() const

• Supporting doxygen features as closely as possible. IMO, the easier the output can be configured to be structured like the overall doxygen output, the easier it is to convince people to use breathe/sphinx for c++. Of course, that is not the only use case, but assuring people that they will feel at home (and then exploit flexibility) may be more appealing to many than providing the flexibility first and thus making it possible to re-create what one was used to. In detail, I think of being able to generate the entire standard doxygen page tree, not just small bits or everything on a single page, and then also:
  • Inheritence diagrams (they should already be basically there and mostly need to be embedded).
  • Links to class list, member list, give the brief on top and link to full description, etc.
  • Also integrate the source files and link there...
• Fully support overloaded qualifiers. I've seen this in the issue tracker, but full overloading support in every sense (display, reference, etc.) really is a prerequisite for any major project. That said:
• Google summer of code candidate. The deadlines are approaching very fast, but maybe breathe is a GSoC candidate that might hit a nerve? I'd neither be a candidate nor have any links to mentor organizations, but maybe that would be an idea. Of course, for a small project, overhead times risk can be more than the potential gain -- does the Sphinx team itself have propositions submitted (maybe jump the bandwagon :) ?
• Add a limitations / todo / wishlist page to the breathe main doc. I know that the issue tracker here on github can be seen as a variant. But it is not as easily accessible, and on the main page, it will serve a more important purpose: telling people what they can expect of the maturity state. Also, it might encourage people to tackle one of them more directly. For example, e.g. like what geany has in addition to a tracker: todo and plugin wishlist pages, which can be as good a project capability description than the actual one :)

Overall, I think we in our project will get started with linking to the old Doxygen pages from the surrounding docs and maybe make the look and feel a bit more Sphinx-ish. But I am happy to keep providing feedback on the above issues because I really believe that this bridge would be a great way to go and will be demanded more and more in the future. In addition, I only tested the easier library of two so far. The other will heavily use template metaprogramming stuff, so it would be interesting to see how that behaves once the more basic parser issues are sorted out.

Kudos for your great work so far, and cheers, Paul

Hi,
I'm trying to use doxygen's command(s) for showing the .h file associated to the class being documented and I get nothing. In particular, I'm using the syntax

\class < name > [ < header-file > ] [ < header-name > ]

without success. Yet the HTML pages produced by doxygen contain the include line, so it is not a config issue. Does breathe simply ignore the info? In your test pages, a 'file xxx.h' entry is sometimes visible but the source code does not contain specific tag to generate it, so how can I get this feature?

Thanks a lot,
Marc

Is there a way we can customize how the infos from doxygen are layed out by breathe like making rubric or subtitles from some part ? The current rendering style is a bit inflexible. Of course, apologized if I missed the informations in the doc. In case it has to be done, where could be the best part to start hacking this ?

When trying to import breathe, I got and exception:

Exception occurred:
File "/home/nijel/gammu/gammu/external/breathe/breathe/renderer/rst/doxygen/init.py", line 4, in
from breathe.renderer.rst.doxygen import compound as compoundrenderer
File "/home/nijel/gammu/gammu/external/breathe/breathe/renderer/rst/doxygen/compound.py", line 250
reftype="ref",
^
SyntaxError: invalid syntax

I am using Python 2.5

No automatic index is generated, also asked here:

http://stackoverflow.com/questions/15290831/index-is-not-generated-in-sphinx

When xml files produces by doxygen changes, a simple make html will not pick up the changes. One must run make clean html which can be slow on large projects.

Sphinx has an outdated hook that could be used to fix this.

This is a duplicate of issue 15, which I tried to reopen, but don't have permission to:

#15

Hi,

Long descriptions in function documentation cause malformed doxygenfunction output. Consider this modified example (from breathe/examples/doxygen/structcmd.h):

/*! \fn int open(const char *pathname,int flags)
    \brief Opens a file descriptor.

    Detailed description.

    \param pathname The name of the descriptor.
    \param flags Opening flags.
*/

(The detailed description is the only change). The generated output looks like this:

int open(const char * pathname, int flags)

    Opens a file descriptor.

    Detailed description.Parameters

        * pathname - The name of the descriptor.
        * flags - Opening flags.

As you can see, the string "Parameters" appears on the same line as the detailed description, instead of on a subsequent line. leaflabs/breathe@0d2f150 contains a modified structcmd.h exhibiting the problem.

Confirmed using cffaa2d (which is master at time of writing) and Sphinx 1.0.4.

When I add formatting (fixed font throught \c or \p or <tt></tt>) to class names in doxygen comments they are not rendered at all.

Here's an example (Out is a class name):

//! Converts \c Out object into a C string.   (1)
//! Converts Out object into a C string.      (2)

(1) will be rendered in sphinx as "Converts object into a C string", where it should be: "Converts Out object into a C string". It works fine in doxygen generated HTML, but not in sphinx.
(2) will be rendered as expected: "Converts Out object into a C string".

Formatting does work if it's not about a class (don't know if it happens to other symbols), i.e. /*! Test \c word */ will be rendered correctly: Test word

Breathe+Sphinx seems to be creating bad LaTeX output for me.

I'm using Breathe 0.7.0 and Sphinx 1.0.8 on a Mac with MacTeX 2010. I've run Doxygen to generate the XML, and I can generate HTML output fine, but when I try to go Sphinx -> LaTeX -> PDF, I get the following error:

  ! Missing \endgroup inserted.
  <inserted text> 
                  \endgroup 
  l.283 }]
           \leavevmode\phantomsection\label{index:}
  ? 
  ! Emergency stop.
  <inserted text> 
                  \endgroup 
  l.283 }]
           \leavevmode\phantomsection\label{index:}
  !  ==> Fatal error occurred, no output PDF file produced!
  Transcript written on snarf.log.

This is with a very simple .rst file with nothing other than a main header and a doxygenindex:: directive.

The bad section of LaTeX is:

\end{description}                                                                                                                                               
\end{quote}                                                                                                                                                     
\emph{Functions}\begin{quote}                                                                                                                                   
\begin{description}                                                                                                                                             
\item[{\phantomsection\label{index:project0alert_8h_1a2908a90fcf870534b032701b20b78aea}\phantomsection\label{index:project0alert_8h_1a2908a90fcf870534b032701b20b78aea}
\begin{DUlineblock}{0em}
\item[] snarf\_alert\_t * \textbf{snarf\_alert\_new}(alert\_severity\_t severity, uint64\_t timestamp)
\end{DUlineblock}                                                                                                                                               
}] \leavevmode\phantomsection\label{index:}

It doesn't like the last line.

There are also a bunch of errors about various labels being multiply defined.

Any idea what's going on? I tried it on my Linux box running the same versions of everything other than Python (2.6 on my Mac, 2.7 on my Linux box) and got the same result.

Currently they all go on one line which doesn't help much. Probably put each one on a new line for functions with more than one argument. Also investigate outputting non-breaking spaces through restructuredText.

It would be really handy to have an option to the renderer that would link back to graphviz output from the HTML renderer of Doxygen. What I was thinking is an app-level option that takes in the path to the html output of Doxygen, and then an :image: option or some such available to classes (and the index directive too, I suppose), templated classes, etc that simply does an img link back to that location.

The app-level option the user gives would simply be the precursor part of the URL that is generated for the img tag. Make sense?

If I want to implement this, what steps should I take? I fumbled around for #44, and I never really figured out how to bolt options in to do it. Any pointers you can provide to help me bootstrap this would be appreciated. I'll take on the task once you help me get the ball rolling.

Hi,

Thanks for making breathe!

It would be very useful if the doxygenenum directive included a list of enumerators and (if present) per-enumerator documentation.

For example, if I say

/** About the enumeration. */
typedef enum some_t {
  VALUE0, /**< Documentation for VALUE0 */
  VALUE1, /**< Documentation for VALUE1 */
} some_t;

I'd like to see VALUE0, VALUE1, and their associated comments in the generated documentation. This information is present in Doxygen's XML output.

I'm using 9ee7310 and Sphinx 1.0.4.

If I understand this correctly, it's a serious issue. We have dozens of functions in our project, all named the same. We can't document these with Breathe, right?

(Besides that, I love that someone is marrying Sphinx to more languages.)

Similarly to the Sphinx toctree directive, it would be very useful if the various directives took a :glob: option which caused them to render all entities whose name matches a pattern. (Having this for doxygenfunction and doxygendefine in particular would really scratch my itches, although I see no reason why it shouldn't be more generally available) .

This would be of particular use in C projects, where the functions in foo.h are often named things like foo_bar(), foo_baz(), etc. Implementing this feature would let me have finer-grained control over the way that I lay out the documentation for a particular file (compared to using doxygenfile), without requiring that I sacrifice concision by specifying where everything goes manually.

I'm willing to give it a go and try to implement it myself, but I'd like to get some advice on how to get the ball rolling.

Here's a vague outline of how I'm thinking about going at it; any comments would be most welcome. (I'm new to the docutils and Sphinx APIs, so it's possible that parts of this won't make any sense). The docs say that finder objects are currently limited to returning a single parser object which matches the user's request. We could instead specify that they return an iterable of matching objects, which renderers would simply render one after another. For a first try, we could say that in the case of multiple matched objects, the renderers put each one within a paragraph node (which seems like the right thing to do for doxygenfunction).

Thanks again for making Breathe! It's made documenting my project tremendously easier, and the results look great.

A nice little side project would be to create a sphinx-autogen equivalent. Something that will generated the appropriate rst stub files with breathe directives for different classes/files/functions/etc.

Happy to advise if anyone would like to contribute,
Michael

It looks like neither doxygentypedef nor doxygenenum are able to properly locate elements within namespaces. For example, if I have this code:

namespace ns {
    typedef int MyInt;
    enum Letters {A, B, C};
}

and some sphinx docs like this:

.. doxygentypedef: ns::MyInt
.. doxygenenum: ns::Letters

then I end up with warnings in my output that MyInt and Letters could not be found in the doxygen xml output.

These directives seem to work fine for equivalent constructs which are not in namespaces, so I assume that it's just an issue with the namespaces themselves.

It would be great if breathe could directly generate documentation in C domain for Sphinx.

http://sphinx.pocoo.org/domains.html#the-c-domain

I tried to look at the code, but I failed to see how such thing could be implemented.

It appears that the doxygenfile directive does not account for enums, typedefs, or functions in namespaces.

For example, with a header file like this:

namespace foo { 
  /** This appears in the documentation */
  class Bar {};

  /** This does not */
  int baz();
}

Bar will appear in the generated documentation while baz will not.

Hi,

With a large project, I have a catch-all everything API page, generated via

.. doxygenindex::
   :project: onboard

It would be great if there was an option which generated the correct table of contents for the resulting docs, as the page is very large and hard to navigate.

OSX, python 2.6, sphinx 1.0.4, doxygen 1.7.2

I get no function parameters displayed, is there a option to set?

It would be nice if breathe offered a similar set of options to what is provided in the autodoc extension (specifically, with the autoclass directive).

In particular, I miss the ability to specify a list of specific member functions to print out via doxygenclass. Presently doxygenclass just dumps out everything.

Along a similar line, it would make sense to allow doxygenfunction to handle functions specified in the form Class::Function or Namespace::Function, since this information is available in the doxygen-generated XML.

Running the testsuite on the latest version of breathe (b4d53b9...) produces the following output for foo::ns::FooStruct:

struct foo::ns::FooStruct
#include <namespacefile.h>
     Documentation here.

Note the line "#include <namespacefile.h>". It is not in the example on the website: http://michaeljones.github.com/breathe/struct.html#example-with-namespace and the documentation of a struct without a namespace (in global scope) doesn't have such line either.

I am using doxygen 1.8.1.2.

Hello,

If I define a macro which takes arguments, like this:

/** 1UL shifted left by 'shift' */
#define BIT(shift)                     (1UL << (shift))

Then the Breathe doxygendefine output looks like this:

BIT
    1UL shifted left by ‘shift’

When I think instead it should look like this:

BIT(shift)
    1UL shifted left by ‘shift’

Or even better yet, like this, with the brief description on the same line to save space:

BIT(shift): 1UL shifted left by ‘shift’ 

I checked the XML output, and the parameters are available in a "param" child of the define's memberdef:

      <memberdef kind="define" id="util_8h_1a0ddea71f077aa1dba6af4e9a108ef526" prot="public" static="no">
        <name>BIT</name>
        <param><defname>shift</defname></param>
        <initializer>(1UL &lt;&lt; (shift))</initializer>
        <briefdescription>
<para>1UL shifted left by &apos;shift&apos; </para>        </briefdescription>
[...]
      </memberdef>