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

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

описание

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

См. также project.

индексы

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

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

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         = https://doc.qt.io/qt/

     ...

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

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

url.examples

Переменная 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/

...

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