c++ doxygen + таблицы дыхания

У меня есть большой проект С++, задокументированный с помощью doxygen. Я хочу использовать дыхание, чтобы делать более приятные руководства. Документация в исходном коде часто содержит такие таблицы:

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

Я создаю документы xml в build/xml с помощью doxygen и запускаю 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. Таблица также отображается в HTML-выводе doxygen. Но он отсутствует в html и pdf, сгенерированных sphinx + breath.

Я не могу найти никаких упоминаний о том, что таблицы doxygen не поддерживаются дыханием. Что мне не хватает?


python-sphinx doxygen
person user1283043    schedule 29.06.2018    source источник
comment
Какая версия доксигена?   -  person albert    schedule 29.06.2018
comment
Я использую doxygen v1.8.14, дышу 4.9.1 и сфинкс 1.7.5. Версия Python по умолчанию — 3, но я думаю, что есть какой-то механизм для выбора версии Python, которую хотят модули.   -  person user1283043    schedule 29.06.2018
comment
Перечитывая вопрос, так что doxygen предоставляет информацию, но дыхание не собирает информацию, так что, вероятно, проблема с дыханием.   -  person albert    schedule 29.06.2018
comment
очевидно, что breath не понимает свойство ‹table› в сгенерированном xml. Он понимает списки, verbatim и т. д. Было бы неплохо предупредить о том, что ‹table› не реализуется дыханием.   -  person user1283043    schedule 29.06.2018

Ответы (2)


arrow_upward
1
arrow_downward

exhale содержит полезную информацию:

Столы

Подсказка

Все, что с этого момента, может вызвать проблемы с Doxygen. Используйте среду \rst verbatim, описанную в разделе "Псевдонимы Doxygen".

Используйте сеточные таблицы!!!

Он поможет вам найти их псевдонимы doxygen:

Псевдонимы

В частности, два псевдонима, предоставляемые 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
 */

Не очень приятно, но я могу жить с этим.

person user1283043    schedule 29.06.2018
comment
Это работает, но таблица RST (очевидно) отображается как искаженный текст, если вы попытаетесь сгенерировать HTML из файла Doxygen. Лучшим обходным решением, которое я смог найти, было использование операторов @if для условной компиляции той или иной версии, что неудобно, но работает. - person David C.; 25.01.2021

arrow_upward
0
arrow_downward

@ user1283043 поделился хорошим ответом, но он будет неполным, если вам нужно генерировать выходные данные как через Sphinx (где ответ работает), так и напрямую из Doxygen (где это не так). Решение, которое я придумал, включает использование операторов Doxygen @if для условной компиляции двух версий одной и той же таблицы.

Для Doxyfile, используемого для создания выходных данных Sphinx, включите ранее упомянутые псевдонимы:

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

Затем включите раздел SPHINX, который может проверять разметка Doxygen:

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.

person David C.    schedule 25.01.2021