Создание файлов конфигурации 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 выведет сгенерированную документацию в директорию, указанную в директории вывода output. Также можно указать дополнительные файлы, которые QDoc должен экспортировать.

HTML.extraimages = extraImage.png \
                   extraImage2.png

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

Конфигурация фреймворка Qt Help

QDoc также экспортирует файл проекта Qt Help в файл с расширением 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

Проекты документации могут ссылаться на API Qt и другие статьи, указав путь к файлу qt.index. При генерации QDoc документации Qt Reference, он также сгенерирует файл индекса, содержащий ссылки на статьи. Другие проекты могут использовать ссылки в файле индекса, чтобы ссылаться на другие статьи и документацию 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.