c++ doxygen + breathe tables

Question

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 German\n` |`<Battery percent>` |
 */

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

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.

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

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.

Answer 2

@user1283043 shared a good answer, but it's incomplete if you need to both generate output via Sphinx (where the answer works) and directly from Doxygen (where it doesn't). The solution I came up with involves the use of Doxygen @if statements to conditionally compile two versions of the same table.

For the Doxyfile used to generate the Sphinx output, include the previously mentioned aliases:

ALIASES  = "rststar=@verbatim embed:rst:leading-asterisk"
ALIASES += "endrst=@endverbatim"

Then enable a SPHINX section that the Doxygen markup can check for:

ENABLED_SECTIONS = SPHINX

With this in place, you can adjust your Doxygen table markup appropriately:

/**
 * @brief Documentation with a table in it
 *
 * These are the allowed values:
 *
 * @if SPHINX
 * @rststar
 * +-------+----------+---------------------------+
 * | Value | Range    | Description               |
 * +=======+==========+===========================+
 * | FOO   | 0..27    | The range for a FOO value |
 * +-------+----------+---------------------------+
 * | BAR   | 91..1372 | The range for a BAR value |
 * +-------+----------+---------------------------+
 * @endrst
 * @else
 * Value | Range    | Description
 * ----- | :------: | -------------------------
 * FOO   | 0..27    | The range for a FOO value
 * BAR   | 91..1372 | The range for a BAR value
 * @endif
 */

It's a bit ugly and awkward, because you need to enter the same text twice, but you get a proper table both when compiled through Doxygen and when compiled through Sphinx/Breathe.