C++ doxygen + 呼吸表

Question

我有一个用 doxygen 记录的大型 c++ 项目。我想用呼吸来制作更好的手册。源代码文档通常包含 table，例如：

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

我在 build/xml 中使用 doxygen 和运行 sphinx 生成了 xml 文档。

doxygen Doxyfile
make html
make latexpdf

目录结构如下所示：

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

一切正常，文档已创建，但缺少 table。我可以在 build/xml/group___somegroup.xml 中看到 table。 table 也显示在 doxygen 的 html 输出中。但是在html和sphinx+breathe.

生成的pdf中都没有

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

Answer 1

exhale 有一些有用的信息：

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!!!

将引导您前往 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
 */

不太好，但我可以接受。

Answer 2

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

的两个版本

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

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

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

ENABLED_SECTIONS = SPHINX

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

/**
 * @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 编译时你都得到了正确的 table。

C++ doxygen + 呼吸表

c++ doxygen + breathe tables

doxygen

python-sphinx