c++ doxygen + breathe tables

I have a large c++ project documented with doxygen. I want to use breathe to make nicer manuals. The in-source documentation often contain tables such as this:

/**
* @var somevar
* @brief some variable
* @defgroup somegroup Some Group
* @details This stores some value in some variable
* | English | German | Parameters |
* |---------|--------|------------|
* | `content of somevar %%s in english.n` | `content of somevar %%s in Germann` |`<Battery percent>` |
*/


I generate the xml docs in build/xml with doxygen and run sphinx to generate the docs.

build/xml

doxygen Doxyfile
make html
make latexpdf


The directory structure looks like this:

├── build
├── Doxyfile
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── somegroup.rst
├── _static
└── _templates


All works fine, documents are created, but the table is missing. I can see the table in the build/xml/group___somegroup.xml. The table is also shown in the html output of doxygen. But it is missing in the html and pdf generated by sphinx + breathe.

build/xml/group___somegroup.xml

I cannot find any reference that doxygen tables are not supported by breathe. What am I missing?

Which version of doxygen?
– albert
Jun 29 at 10:54

I'm using doxygen v1.8.14, breathe 4.9.1 and sphinx 1.7.5. default python version is 3, but I think there is some mechanism to choose the python version the modules want.
– user1283043
Jun 29 at 10:56

Rereading question, so doxygen supplies the information but breathe does not pick up the information, so probably a breathe problem.
– albert
Jun 29 at 11:00

obviously breathe does not understand the <table> property in the generated xml. It understands lists, verbatim etc. A warning would have been nice about <table> not beeing implemented by breathe.
– user1283043
Jun 29 at 11:04

1 Answer
1

exhale has some useful info:

Tables

Tip

Everything from here on may cause issues with Doxygen. Use the rst verbatim environment described in the Doxygen Aliases section.

Use grid tables!!!

The will guide you to their doxygen aliases:

ALIASES

In particular, the two aliases Exhale provides come from Breathe, and allow you to wield full-blown reStructuredText (including directives, grid tables, and more) in a “verbatim” environment. The aliases as sent to Doxygen:

# Allow for rst directives and advanced functions e.g. grid tables
ALIASES = "rst=verbatim embed:rst:leading-asterisk"
ALIASES += "endrst=endverbatim"


This allows you to do something like this in your code:

/**
* file
*
* brief This file does not even exist in the real world.
*
* rst
* There is a :math:`N^2` environment for reStructuredText!
*
* +-------------------+-------------------+
* | Grid Tables | Are Beautiful |
* +===================+===================+
* | Easy to read | In code and docs |
* +-------------------+-------------------+
* | Exceptionally flexible and powerful |
* +-------+-------+-------+-------+-------+
* | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 |
* +-------+-------+-------+-------+-------+
*
* endrst
*/


Not so nice, but I can live with that.

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.