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

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

описание

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

См. также project.

индексы

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

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.