c++ doxygen +呼吸表

Question

我有一个用doxygen记录的大型c++项目。我想用“呼吸”来制作更好的手册。源代码中的文档通常包含这样的表：

/**
 * @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>` |
 */

我用doxygen在build/xml中生成xml，然后运行sphinx来生成文档。

doxygen Doxyfile
make html
make latexpdf

目录结构如下所示：

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

所有操作都很好，创建了文档，但缺少该表。我可以在build/xml/group___somegroup.xml中看到这张桌子。该表还显示在doxygen的html输出中。但在斯芬克斯+ breathe生成的html和pdf中缺少了它。

我找不到doxygen表不受find支持的任何引用。我遗漏了什么？

Answer 1

呼出有一些有用的信息：

表格 提示 从现在开始，一切都会引起氧气的问题。使用Doxygen部分中描述的\rst逐字环境。 使用网格表！

“遗嘱”将引导您到达他们的doxygen别名

别名 特别是，Exhale提供的两个别名来自wield，并允许您在“逐字”环境中使用完整的reStructuredText (包括指令、网格表等)。发送给Doxygen的别名：

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

这允许您在代码中执行类似的操作：

/**
 * \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
 */

不太好，但我能忍受。

Answer 2

@where 1283043共享了一个很好的答案，但是如果您需要通过Sphinx (答案有效的地方)和直接从doesn(不需要的地方)生成输出，那么它是不完整的。我想出的解决方案涉及使用DO2 @if语句有条件地编译同一个表的两个版本。

对于用于生成Sphinx输出的Doxyfile，包括前面提到的别名：

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

然后启用for标记可以检查的SPHINX部分：

ENABLED_SECTIONS = SPHINX

在此基础上，您可以适当地调整DO2表标记：

/**
 * @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
 */

这有点丑陋和尴尬，因为您需要输入两次相同的文本，但无论是通过both编译还是在Sphinx/Breathe编译时，都会得到一个合适的表。