librelist archives

« back to archive

Fwd: guidance for usage breathe with existing doxygen set up on a large project

Fwd: guidance for usage breathe with existing doxygen set up on a large project

From:
Arnaud Gelas
Date:
2011-08-06 @ 19:01
Hi,

I have just found out about breathe, and it looks great!!

I would like to give it a try on one project (rather large) where we use 
doxygen (and not familiar with sphinx), where the internal structure of 
the project is as follows:

Project
     |______ Code
                     |______ Core
                                     |______ include
                                     |______ src
                                     |______ test

                     |______ IO
                                     |______ include
                                     |______ src
                                     |______ test

     |______ Examples
                     |______ Core
                     |______ IO

     |______ Utilities
                     |______ Doxygen


If I understood correctly, the easiest to give it a try is to:

    * make sure GENERATE_XML = YES in doxygen.config
    * generate sphinx configuration files using sphinx-quickstart for my
      configuration

Then I am not so sure about next steps:

    * I should add doxygenclass:: ... (for all the classes that should
      appear in the documentation) in one rst file ?? so if I want all
      the class to show up, I should add all of them ??
    * I should add something like the following ?

breathe_projects = {
     "Project":"/path/to/project/doxygen/xml/",
     }


Thanks in advance for your help and guidance,
Arnaud

Re: [breathe] Fwd: guidance for usage breathe with existing doxygen set up on a large project

From:
Michael Jones
Date:
2011-08-07 @ 02:30
Hi,

Thanks for checking out breath. Always happy to hear when someone
thinks it might help.

You're definitely on the right track. You want to:

  - make sure GENERATE_XML = YES in doxygen.config
  - generate sphinx configuration files using sphinx-quickstart for my
configuration
  - add breathe as an extension to the sphinx conf.py file (append
"breathe" to the "extensions" variable in conf.py which is string
list)
  - set the "breathe_projects" map with your project name and path as
you suggest.
  - for ease of use, set "breathe_default_project" to the name of your
project so breathe knows to use that everytime

Then there are two options:

  - To get a large dump of all the doxygen information you can add "..
doxygenindex::" to one of your rst pages. That will search through all
the doxygen xml and output everything to one page which will probably
be too much if you have a large project.

  - To have more precise control and be able to split the classes,
function, etc over multiple pages, you can use individual "..
doxygenclass::", ".. doxygenfunction", etc, directives. These will
only call in particular parts of your code base and can be placed on
separate pages (different .rst files) to keep things more organised.
There are a few different directives described in the docs.

Unfortunately, there is currently no way to generate nice multiple
page documentation with a single directive. There is also no way at
the moment of automatically generating a nice set of .rst files that
reference one class each. It would be good to look into different
approaches for this but it hasn't been done yet.

There are some docs available here:  http://michaeljones.github.com/breathe/

But please feel free to ask more questions. And if you find any parts
of the documentation confusing please say and I'll try to improve it.

And finally, thanks for being the first person to use the breathe
mailing list :)

Michael



On Sun, Aug 7, 2011 at 7:01 AM, Arnaud Gelas
<arnaud_gelas@hms.harvard.edu> wrote:
> Hi,
>
> I have just found out about breathe, and it looks great!!
>
> I would like to give it a try on one project (rather large) where we use
> doxygen (and not familiar with sphinx), where the internal structure of the
> project is as follows:
>
> Project
>     |______ Code
>                     |______ Core
>                                     |______ include
>                                     |______ src
>                                     |______ test
>
>                     |______ IO
>                                     |______ include
>                                     |______ src
>                                     |______ test
>
>     |______ Examples
>                     |______ Core
>                     |______ IO
>
>     |______ Utilities
>                     |______ Doxygen
>
>
> If I understood correctly, the easiest to give it a try is to:
>
> make sure GENERATE_XML = YES in doxygen.config
> generate sphinx configuration files using sphinx-quickstart for my
> configuration
>
> Then I am not so sure about next steps:
>
> I should add doxygenclass:: ... (for all the classes that should appear in
> the documentation) in one rst file ?? so if I want all the class to show up,
> I should add all of them ??
> I should add something like the following ?
>
> breathe_projects = {
>     "Project":"/path/to/project/doxygen/xml/",
>     }
>
>
> Thanks in advance for your help and guidance,
> Arnaud
>