Создание файлов конфигурации QDoc

Для генерации документации QDoc использует файлы конфигурации с расширением qdocconf, в которых хранятся настройки.

Статья Файл конфигурации QDoc подробно описывает различные переменные конфигурации.

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

Настройки конфигурации QDoc могут храниться в одном файле qdocconf, но также могут находиться в других файлах qdocconf. Команда include(<filepath>) позволяет файлам конфигурации включать другие файлы конфигурации.

QDoc имеет два типа вывода: HTML-документацию и документацию в формате DITA XML. Основное различие между этими двумя типами вывода заключается в том, что для HTML-документации необходимо указать информацию об HTML-стилизации в файлах конфигурации. Для документации DITA XML это не требуется, и процесс стилизации документации DITA может выполняться отдельно в более позднее время. Следовательно, DITA XML более гибкий, позволяя применять различные стили к одной и той же информации.

Для запуска qdoc, необходимо указать файл конфигурации проекта в качестве аргумента.

qdoc project.qdocconf

Файл конфигурации проекта содержит информацию, используемую qdoc для создания документации.

Информация о проекте

QDoc использует информацию project для генерации документации.

project = QDoc Project
description = Sample QDoc project

Директории ввода и вывода

Указание пути к директориям исходного кода позволяет QDoc найти исходные файлы и сгенерировать документацию.

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDoc будет обрабатывать заголовки и исходные файлы, указанные в переменной fileextensions.

Аналогично, QDoc нуждается в пути к выходной директории. Переменная outputformats определяет тип документации. Эти переменные должны храниться в отдельных файлах конфигурации для модульного построения документации.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc может разрешать пути относительно файла qdocconf, а также переменные среды.

Примечание: При каждом запуске QDoc выходная директория удаляется.

Дополнительные файлы

QDoc будет выводить сгенерированную документацию в директорию, указанную в каталоге вывода. Также можно указать дополнительные файлы, которые QDoc должен экспортировать.

HTML.extraimages = extraImage.png \
                   extraImage2.png

Файлы extraImage.png и extraImage2.png будут скопированы в директорию вывода HTML.

Настройка Qt Help Framework

QDoc также экспортирует файл Qt Help Project, в файле qhp. Файл qhp затем используется qhelpgenerator для упаковки документации в файл qch. Qt Creator и Qt Assistant читают файл qch для отображения документации.

Статья Создание файлов проекта справки описывает параметры конфигурации.

Конфигурация HTML

QDoc имеет генератор HTML, который экспортирует набор документации в HTML-файлы с использованием различных настроек конфигурации. QDoc поместит сгенерированную документацию в директорию, указанную переменной outputdir.

outputformats = HTML
outputdir =  <path to output directory>

QDoc должен знать, где находятся стили и шаблоны для генерации HTML. Обычно в директории шаблонов находятся директории scripts, images, и style, содержащие скрипты и файлы CSS.

Основные переменные конфигурации:

HTML.postheader
HTML.postpostheader
HTML.postheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

Переменная HTML.headerstyles вставляет информацию о стиле в HTML-файл, а HTML.stylesheets определяет, какие файлы QDoc должен скопировать в выходную директорию. Кроме того, QDoc встроит строку в переменные postheader, footer и связанные с ними в каждый HTML-файл.

Специализированные переменные конфигурации описывают использование каждой переменной.

Qt Справочник

Проекты документации могут ссылаться на Qt API и другие статьи, указав путь к файлу qt.index. При генерации QDoc справочной документации Qt, он также сгенерирует файл индекса, содержащий URL-адреса статей. Другие проекты могут использовать ссылки в файле индекса для ссылки на другие статьи и API-документацию в Qt.

indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index

Можно указать несколько файлов индекса из нескольких проектов.

Макросы и другие конфигурации

Существуют макросы для подстановки HTML-символов, которые полезны для генерации определённых HTML-символов.

macro.pi.HTML         = "Π"

Указанный фрагмент кода заменит все вхождения \\pi на &Pi, в файле HTML, что отобразится как символ греческого алфавита Π в браузере.

Добавления QML

QDoc может анализировать файлы QML для комментариев QDoc. QDoc будет анализировать файлы с расширением QML, .qml, если тип расширения включён в переменную fileextensions.

Также сгенерированные HTML-файлы могут иметь префикс и суффикс после имени модуля QML, указанные в файле конфигурации QDoc.

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

См. также: outputprefixes, outputsuffixes.