Создание файлов конфигурации 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

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-файл.

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

Файлы индекса QDoc

Проекты документации могут ссылаться на цели в других проектах, указав набор зависимостей или набор прямых путей к файлам индекса(ов), от которых зависит этот проект. Когда QDoc генерирует документацию для проекта, он также сгенерирует файл .index, содержащий URL-адреса каждой связываемой сущности в проекте. Другие проекты могут затем определить зависимость от файла индекса, чтобы ссылаться на документацию в рамках этого проекта.

См. также: depends и indexes.

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

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

macro.pi.HTML         = "Π"

В примере кода любая строка \\pi будет заменена на &Pi; в HTML-файле она будет отображаться как греческий символ Π при просмотре в браузере.

См. также: macro.

Дополнения QML

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

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

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

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