Файл конфигурации QDoc

Перед запуском QDoc необходимо создать файл конфигурации QDoc, чтобы указать QDoc, где искать исходные файлы, содержащие комментарии QDoc. Путь к файлу конфигурации передаётся QDoc в командной строке:

/current/dir$ ../../bin/qdoc ./config.qdocconf

Общее описание

Файл конфигурации представляет собой список записей вида "переменная = значение". Используя переменные конфигурации, можно определить, где QDoc должен искать различные исходные файлы, изображения и примеры, куда поместить сгенерированную документацию и т.д. Файл конфигурации также может содержать директивы, такие как include. Пример см. в файле минимальной конфигурации qdocconf.

Вы также можете использовать переменные конфигурации для настройки поддержки QDoc производных проектов, т.е. QDoc может генерировать ссылки в документации вашего проекта на элементы онлайн-документации Qt. См. раздел Поддержка производных проектов.

Идентификатор корректной переменной конфигурации может содержать заглавные и строчные буквы, цифры и знак подчеркивания, '_' .

Значение переменной конфигурации можно установить с помощью символа '=' или '+='. Разница заключается в том, что '=' перезаписывает предыдущее значение, а '+=' добавляет новое значение к текущему.

Значения некоторых переменных конфигурации интерпретируются как список строк, например: sourcedirs, в то время как другие обрабатываются как одиночная строка. Двойные кавычки вокруг значения строки необязательны, но их использование позволяет использовать специальные символы, такие как '=' и ' " ' внутри строки значения, например:

HTML.postheader = "<a href=\"index.html\">Home</a>"

Если запись занимает несколько строк, используйте обратную косую черту в конце каждой строки, кроме последней:

sourcedirs = kernel tools widgets

Это можно записать как:

sourcedirs = kernel \
             tools \
             widgets

Если значение занимает несколько строк, но интерпретируется как единственная строка, строки объединяются пробелами.

Расширение значений конфигурации

QDoc поддерживает расширение переменных среды в файлах конфигурации. Например, модули Qt полагаются на переменную среды QT_INSTALL_DOCS для включения определений, относящихся ко всем проектам документации модулей Qt:

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

Переменная для расширения предваряется символом '$'. Для использования символа '$' в строке значения необходимо экранировать его обратной косой чертой: '\$'.

Начиная с QDoc 6.0, значения можно расширять также из других переменных конфигурации. Помимо синтаксиса $variable, также ${variable} является допустимым. Последний исключает необходимость разделять имя переменной пробелами или непеременными символами. Например:

baseurl = https://doc.qt.io/
...
url = ${baseurl}qtcreator

Если целевая переменная относится к списку строк, они будут объединены пробелами в расширенном значении:

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

Также можно управлять символом, используемым для объединения списка строк:

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

Поскольку расширение выполняется после считывания всех переменных, порядок их определения не имеет значения.

Примечание: Вложенное расширение переменных не поддерживается.

Расширение переменных среды

При расширении переменных среды синтаксис ${variable} имеет другое поведение по сравнению с $variable. Первый расширяет содержимое переменной на месте, чтобы оно обрабатывалось как часть файла конфигурации, а второй просто назначает содержимое в качестве значения для текущей переменной конфигурации. Это имеет последствия, если переменная среды содержит список элементов, разделенных пробелами или другим форматированием, распознаваемым QDoc.

Например, если значение переменной среды SRCDIRS равно "../src/a ../src/b", то

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

Переменные конфигурации

Список переменных

• alias
• Cpp.ignoredirectives
• Cpp.ignoretokens
• defines
• depends
• exampledirs
• examples
• examples.fileextensions
• excludedirs
• excludefiles
• extraimages
• falsehoods
• headerdirs
• headers
• headers.fileextensions
• HTML.footer
• HTML.postheader
• HTML.style
• ignorewords
• ignoresince
• imagedirs
• images
• images.fileextensions
• indexes
• language
• locationinfo
• macro
• manifestmeta
• navigation
• outputdir
• outputformats
• outputprefixes
• outputsuffixes
• project
• sourcedirs
• sources
• sources.fileextensions
• spurious
• tabsize
• url
• url.examples
• version
• versionsym
• warninglimit

Категории

• Общие переменные конфигурации
• Переменные конфигурации, специфичные для C++
• Переменные конфигурации, специфичные для формата

Примеры файлов конфигурации

• Файл минимальной конфигурации: minimum.qdocconf
• Файл конфигурации Qt: qtgui.qdocconf