Автогенерация справки из Doxygen-комментариев: пайплайн Doxygen → HTML → qhp → qch

Введение

Поддерживать пользовательскую справку и API-документацию для разработчиков как два полностью независимых источника — затратно и чревато рассинхронизацией. Doxygen умеет генерировать не только обычный HTML, но и сразу .qhp-файл вместе со скомпилированным .qch — это позволяет автоматизировать получение готового Qt Help справочника прямо из комментариев в исходном коде (рассмотренных в одной из предыдущих статей цикла про документирование), без ручного написания .qhp вручную. В статье настроим такой автоматизированный пайплайн.

Концепция

Doxygen поддерживает генерацию вывода в формате Qt Help через специальные опции конфигурации (GENERATE_QHP, QHP_NAMESPACE, QHG_LOCATION) — при включении этих опций Doxygen, помимо обычных HTML-страниц документации классов, автоматически создаёт корректный .qhp-файл с TOC, построенным на основе иерархии документированных сущностей (классы, модули, файлы), и при указании пути к qhelpgenerator через QHG_LOCATION сразу же компилирует результат в .qch одним запуском.

Пример кода: Автогенерация справки из Doxygen-комментариев

# Doxyfile — ключевые настройки для генерации Qt Help из Doxygen-документации

PROJECT_NAME           = "MySensorLibrary"
INPUT                  = ./src ./include
RECURSIVE              = YES
GENERATE_HTML           = YES
GENERATE_QHP            = YES

QHP_NAMESPACE           = com.mycompany.mysensorlibrary.1.0
QHP_VIRTUAL_FOLDER      = doc
QHP_CUST_FILTER_NAME    = "MySensorLibrary 1.0"
QHP_CUST_FILTER_ATTRS   = mysensorlibrary;1.0

# Путь к исполняемому файлу qhelpgenerator —
# при указании Doxygen сам скомпилирует .qhp в .qch после генерации HTML
QHG_LOCATION            = /opt/Qt/6.7.0/gcc_64/libexec/qhelpgenerator

GENERATE_LATEX          = NO
JAVADOC_AUTOBRIEF       = YES
PREDEFINED              = Q_OBJECT= Q_INVOKABLE= Q_PROPERTY(x)=

#!/usr/bin/env bash
# build_help.sh — автоматизация генерации справки как часть процесса сборки

set -e

echo "Генерация документации через Doxygen..."
doxygen Doxyfile

QCH_FILE="html/com.mycompany.mysensorlibrary.1.0.qch"

if [ -f "$QCH_FILE" ]; then
    echo "Справка успешно собрана: $QCH_FILE"
    cp "$QCH_FILE" ../resources/docs/mysensorlibrary.qch
else
    echo "Ошибка: файл .qch не был создан" >&2
    exit 1
fi

# CMakeLists.txt — интеграция генерации справки в общую сборку проекта
find_program(DOXYGEN_EXECUTABLE doxygen)

if (DOXYGEN_EXECUTABLE)
    add_custom_target(GenerateHelp
        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_SOURCE_DIR}/Doxyfile
        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
        COMMENT "Генерация Qt Help справочника из Doxygen-комментариев"
    )
    add_dependencies(MyApp GenerateHelp) # справка собирается перед основным приложением
endif()

Пояснения к коду

Опции QHP_NAMESPACE, QHP_VIRTUAL_FOLDER, QHP_CUST_FILTER_NAME/QHP_CUST_FILTER_ATTRS в Doxyfile соответствуют ровно тем же понятиям .qhp-файла, что мы разбирали в первой статье цикла, но Doxygen генерирует их автоматически на основе структуры документированного кода — TOC строится из иерархии namespace/класс/метод, а индекс ключевых слов — из имён документированных сущностей. Указание QHG_LOCATION с путём к реальному исполняемому файлу qhelpgenerator (он входит в установку Qt SDK) заставляет Doxygen самостоятельно выполнить финальный шаг компиляции .qhp в .qch, не требуя отдельного ручного вызова.

Скрипт build_help.sh и фрагмент CMake показывают два способа интеграции этого процесса в общий пайплайн сборки — как явный shell-скрипт для CI, и как дополнительная цель CMake (GenerateHelp), от которой зависит основная цель приложения, гарантируя, что свежая справка собирается перед каждой сборкой релиза.

Подводные камни

Качество автоматически сгенерированного TOC из структуры кода может не подходить для конечного пользователя-непрограммиста. Этот пайплайн отлично подходит для документации API библиотек, адресованной разработчикам (для которых структура «класс → метод» естественна), но для пользовательской справки приложения (где нужна структура «задача → решение», разобранная во второй статье цикла) такая автогенерация не заменяет вручную продуманную навигацию — два разных типа справки часто требуют разных подходов в рамках одного продукта.
Несовпадение версии qhelpgenerator, указанной в QHG_LOCATION, с версией Qt, под которую собирается само приложение. Если в системе CI установлено несколько версий Qt SDK, путь в QHG_LOCATION может случайно указывать на устаревшую или несовместимую версию инструмента, порождая .qch, который не полностью корректно открывается в QHelpEngine целевой версии приложения.
PREDEFINED без корректной настройки макросов Qt (как уже отмечалось в статье про Doxygen) может приводить к неполной или искажённой структуре документации, генерируемой для классов с Q_OBJECT/Q_PROPERTY — это напрямую отражается и на сгенерированном TOC справки Qt Help, не только на обычном HTML-выводе.
Отсутствие проверки успешности генерации .qch в автоматизированном пайплайне. Если Doxygen завершился с ошибками (например, из-за синтаксически некорректных комментариев), но без полного отказа всего процесса, итоговый .qch может оказаться неполным или вовсе не сгенерированным — скрипт build_help.sh в примере явно проверяет существование результирующего файла именно для того, чтобы не пропустить такой «тихий» частичный сбой дальше по пайплайну сборки.