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

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

См. также: 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.