Поддержка производных проектов

Некоторые переменные конфигурации позволяют использовать QDoc для поддержки проектов на базе Qt. Они позволяют вашему проекту содержать ссылки на онлайн-документацию Qt, что означает, что QDoc сможет создавать ссылки на документацию по классам, без явных команд связывания.

описание

Переменная description содержит краткое описание связанного проекта.

См. также project.

индексы

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

Например, чтобы сделать производный проект Qt содержащим ссылки на документацию Qt Reference, вам нужно указать связанный файл индекса:

indexes = $QTDIR/doc/html/qt.index

См. также project и url.

project

Переменная project предоставляет имя проекта, связанного с файлом .qdocconf.

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

project = QtCreator

Это приведет к созданию файла индекса с именем qtcreator.index.

См. также описание и индексы.

url

Переменная url содержит базовый URL для документации по ссылкам, связанной с текущим проектом.

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

project     = Qt
description = Qt Reference Documentation
url         = http://doc.qt.io/qt-4.8/

     ...

Это гарантирует, что всякий раз, когда используется qt.index для генерации ссылок на, например, классы Qt, базовый URL является http://doc.qt.io/qt-4.8/.

См. также индексы и url.примеры.

url.примеры

Переменная url.examples хранит базовый URL для примеров, связанных с текущим проектом.

Если определено, ссылка на каталог проекта примеров генерируется в конце каждой страницы документации примера. Переменная url.examples относится к корневому каталогу примеров, связанных с этим проектом; это может быть ссылка на онлайн-репозиторий (начинающийся с http:// или https://) или на локальную файловую систему (file://).

Если url.examples не определено, QDoc выведет список файлов и изображений примера.

Например, при таких определениях:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
examplesinstallpath = corelib

Затем, для следующей команды \example:

/*!
    \example threads/semaphores
    ...
*/

QDoc генерирует ссылку на https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores.

Если URL содержит дополнительные компоненты (например, строку запроса) после пути к примеру, \1 может использоваться в качестве заглушки для пути:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
examplesinstallpath = corelib

При той же команде \example, что и выше, и при условии, что $QT_VER расширяется до 5.13, сгенерированный URL является https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13.

Переменная url.examples была введена в QDoc версии 5.13.

См. также url, examplesinstallpath и \example.

Как поддерживать производные проекты

Эта функция использует исчерпывающие индексы, сгенерированные QDoc при создании документации по ссылкам Qt.

Например, qtgui.qdocconf (файл конфигурации для Qt) содержит следующие определения переменных:

project     = Qt
description = Qt Reference Documentation
url         = http://doc.qt.io/qt-4.8/

...

Имя переменной project используется для формирования имени файла индекса; в этом случае создаётся файл qt.index. URL url хранится в файле индекса. Затем QDoc будет использовать его в качестве базового URL при построении ссылок на классы, функции и другие элементы, перечисленные в индексе.