c++ doxygen + 呼吸表答案

【问题标题】：c++ doxygen + breathe tablesc++ doxygen + 呼吸表
【发布时间】：2018-12-08 12:37:44
【问题描述】：

我有一个用 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 输出中。但是sphinx+breath生成的html和pdf中缺少它。

我找不到任何关于 doxygen 表不受呼吸支持的参考。我错过了什么？

【问题讨论】：

doxygen 的哪个版本？
我正在使用 doxygen v1.8.14，呼吸 4.9.1 和 sphinx 1.7.5。默认python版本是3，但我认为有一些机制可以选择模块想要的python版本。
重读问题，所以 doxygen 提供了信息，但呼吸没有获取信息，所以可能是呼吸问题。
显然呼吸不理解生成的xml中的属性。它可以理解列表、逐字记录等。关于
没有通过呼吸实现的警告会很好。

标签： doxygen python-sphinx

【解决方案1】：

exhale 有一些有用的信息：

表格

提示

从这里开始的一切都可能导致 Doxygen 出现问题。使用 Doxygen Aliases 部分中描述的 \rst verbatim 环境。

使用网格表！！！

将引导您到their doxygen aliases：

别名

特别是，Exhale 提供的两个别名来自 Breathe，允许您在“逐字”环境中使用成熟的 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
 */

不太好，但我可以忍受。

【讨论】：

这可行，但如果您尝试从 Doxygen 生成 HTML，RST 表（显然）会呈现为损坏的文本。我能找到的最好的解决方法是使用@if 语句有条件地编译一个或另一个版本，这很尴尬，但有效。

【解决方案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 编译时都会得到一个正确的表格。

【讨论】：