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

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

описание

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

См. также project.

индексы

Переменная indexes-variable[индексы} определяет набор путей к файлам индексов для загрузки.

indexes = \
    $QT_INSTALL_DOCS/qtcore/qtcore.index \
    $SOME_OTHER_PROJECT/doc/foo.index

Переменная indexes предоставляет альтернативу depends для определения зависимостей проекта. Поскольку предоставляются прямые пути, при вызове QDoc не требуются никакие опции командной строки -indexdir.

Определять зависимости можно с помощью любой из этих переменных. Документация Qt использует только переменную depends.

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

project

Переменная project предоставляет имя для проекта, связанного с файлом .qdocconf. Это обязательная переменная, которую все проекты должны установить.

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

project = QtCreator

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

Если имя проекта содержит пробелы или специальные символы, они заменяются дефисами ('-') в сгенерированном имени файла индекса.

См. также depends, indexes и описание.

url

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

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

project     = QtCore
description = Qt Core Reference Documentation
url         = https://doc.qt.io/qt/

...

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

См. также depends, индексы и 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 GUI) содержит следующие определения переменных:

project     = QtGui
description = Qt GUI Reference Documentation
url         = http://doc.qt.io/qt/

...

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

См. также depends, индексы, project и url.