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输出中。但是狮身人面像+呼吸产生的html和pdf中缺少它。

我找不到任何有关呼吸不支持doxygen表的参考。我想念什么？

Answer 1

exhale有一些有用的信息：

表格

提示

从这里开始的所有内容都可能导致Doxygen出现问题。使用“ Doxygen Aliases”部分中描述的\ r逐字环境。

使用网格表！

它将引导您进入their doxygen aliases：

别名

尤其是，Exhale提供的两个别名来自Breathe，使您可以在“ verbatim”环境中使用完整的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

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

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

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

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

ENABLED_SECTIONS = SPHINX

有了这个，你可以适当地调整你的 Doxygen 表标记：

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

这有点难看和尴尬，因为你需要输入相同的文本两次，但是通过 Doxygen 编译和通过 Sphinx/Breathe 编译时你都会得到一个正确的表格。

C ++ Doxygen +呼吸表

2 个答案: