Создание файлов конфигурации 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 в файле 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 Documentation, он также сгенерирует файл индекса, содержащий 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.