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

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

Описание

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

См. также project.

Индексы

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

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

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

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

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

Проект

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

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

project = QtCreator

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

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

См. также depends, indexes и description.

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, indexes и 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, indexes, project и url.