Общие переменные конфигурации

С помощью общих переменных конфигурации QDoc вы можете определить, где QDoc найдёт различные исходные файлы для генерации документации, а также каталог для размещения сгенерированной документации. Вы также можете произвести некоторые незначительные изменения в самом QDoc, контролируя его вывод и поведение обработки.

alias

Переменная alias переименовывает команду QDoc.

Общая синтаксис alias.original-command-name = temporary-command-name.

alias.e = i

Это переименовывает встроенную команду \e (курсив) в \i. Переменная alias часто используется для обеспечения совместимости.

См. также макрос.

codeindent

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

В QDoc изначально использовалось жёстко заданное значение в четыре пробела для отступа кода, чтобы гарантировать, что фрагменты кода легко можно было отличить от окружающего текста. Поскольку мы можем использовать таблицы стилей для изменения внешнего вида определённых типов HTML-элементов, этот уровень отступа не всегда необходим.

codeprefix, codesuffix

Переменные codeprefix и codesuffix определяют пару строк, в которые заключён каждый фрагмент кода.

defines

Переменная defines определяет символы препроцессора C++, которые QDoc будет распознавать и на которые будет реагировать.

Когда символ препроцессора задаётся с помощью переменной defines, вы также можете использовать команду \if для включения документации, которая будет включена только в том случае, если символ препроцессора определён.

Значения переменной представляют собой регулярные выражения (см. QRegExp для подробностей). По умолчанию символ не определён, что означает, что код, защищённый #ifdef...#endif, будет проигнорирован.

defines = Q_QDOC \
          QT_.*_SUPPORT \
          QT_.*_LIB \
          QT_COMPAT \
          QT3_SUPPORT \
          Q_OS_.* \
          Q_BYTE_ORDER \
          __cplusplus

Это гарантирует, что QDoc обработает код, который требует определения этих символов. Например:

#ifdef Q_OS_WIN
  HDC getDC() const;
  void releaseDC(HDC) const;
#endif

Поскольку регулярное выражение Q_OS_.* (заданное с помощью переменной defines), соответствует Q_OS_WIN, QDoc обработает код внутри #ifdef и #endif в нашем примере.

Вы также можете определить символы препроцессора вручную в командной строке, используя опцию -D. Например:

currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf

В этом случае опция -D гарантирует, что символ препроцессора consoleedition определён, когда QDoc обрабатывает исходные файлы, определённые в файле qtgui.qdocconf.

См. также falsehoods и \if.

edition

Переменная edition определяет модули, включённые в каждый выпуск пакета, и предоставляет QDoc информацию для предоставления списков классов для каждого выпуска.

Эта функция в основном используется при предоставлении документации для пакетов Qt.

Переменная edition всегда используется с конкретным именем выпуска для определения модулей для этого выпуска:

edition.Console      = QtCore QtNetwork QtSql QtXml
edition.Desktop      = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
                       QtDesigner QtAssistant Qt3Support QAxContainer \
                       QAxServer
edition.DesktopLight = QtCore QtGui Qt3SupportLight

В приведённых выше примерах выпуск Console включает только содержимое четырёх модулей. Только классы из этих модулей будут использоваться при использовании команды generatelist для генерации списка классов для этого выпуска:

\generatelist{classesbyedition Console}

exampledirs

Переменная exampledirs определяет каталоги, содержащие исходный код файлов примеров.

Переменные examples и exampledirs используются командами \quotefromfile, \quotefile и \example. Если переменные examples и exampledirs определены, QDoc будет искать в обоих, сначала в examples, затем в exampledirs.

QDoc будет искать в каталогах в указанном порядке и примет первый найденный соответствующий файл. Он будет искать только в указанных каталогах, а не в подкаталогах.

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

При обработке

\quotefromfile widgets/calculator/calculator.cpp

QDoc проверит, есть ли файл с именем calculator.cpp в списке значений переменной examples. Если его нет, он будет искать в переменной exampledirs, и сначала проверит, существует ли файл с именем

$QTDIR/doc/src/widgets/calculator/calculator.cpp

Если его нет, QDoc продолжит поиск файла с именем

$QTDIR/examples/widgets/calculator/calculator.cpp

и так далее.

См. также examples.

examples

Переменная examples позволяет указать отдельные файлы примеров дополнительно к тем, которые расположены в каталогах, указанных переменной exampledirs.

Переменные examples и exampledirs используются командами \quotefromfile, \quotefile и \example. Если переменные examples и exampledirs определены, QDoc будет искать в обоих, сначала в examples, затем в exampledirs.

QDoc будет искать среди значений, перечисленных для переменной examples, в указанном порядке и примет первый найденный.

Для подробного примера см. команду exampledirs. Но обратите внимание, что если вы знаете, что файл указан в переменной examples, вам не нужно указывать его путь:

\quotefromfile calculator.cpp

См. также exampledirs.

examples.fileextensions

Переменная examples.fileextensions определяет расширения файлов, которые qdoc будет искать при сборе файлов примеров для отображения в документации.

По умолчанию расширения — *.cpp, *.h, *.js, *.xq, *.svg, *.xml и *.ui.

Расширения задаются как стандартные выражения с подстановкой символов. Вы можете добавить расширение файла к фильтру с помощью '+='. Например:

examples.fileextensions += *.qrc

См. также headers.fileextensions.

excludedirs

Переменная excludedirs предназначена для перечисления каталогов, которые не должны обрабатываться qdoc, даже если те же каталоги включены переменными sourcedirs или headerdirs.

Например:

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

При выполнении QDoc исключит указанные каталоги из дальнейшего рассмотрения. Файлы в этих каталогах не будут читаться qdoc.

См. также excludefiles.

excludefiles

Переменная excludefiles позволяет указать отдельные файлы, которые не должны обрабатываться qdoc.

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

Если вы включите вышеуказанное в свой файл qdocconf для qtbase, документация класса QWidget не будет сгенерирована.

Начиная с Qt 5.6, переменная excludefiles также распознаёт простые подстановки символов ('*' и '?'). Например, чтобы исключить все частные заголовочные файлы Qt из парсинга, задайте следующее:

excludefiles += "*_p.h"

См. также excludedirs.

extraimages

Переменная extraimages сообщает QDoc о включении определённых изображений в сгенерированную документацию.

QDoc не распознаёт изображения, используемые в HTML (или любом другом языке разметки). Если мы хотим скопировать изображения из каталогов, указанных в imagedirs (сами изображения должны находиться в этих каталогах), в каталог вывода, мы должны указать изображения с помощью переменной extraimages.

Общая синтаксис extraimages.format = image. Расширение файла необязательно.

Например, в qtgui.qdocconf мы используем несколько изображений в переменной HTML.postheader, значением которой является чистый HTML. По этой причине эти изображения задаются с помощью переменной extraimages:

extraimages.HTML = qt-logo

См. также images и imagedirs.

falsehoods

Переменная falsehoods определяет истинность указанных символов препроцессора как ложную.

Если эта переменная не установлена для символа препроцессора, QDoc предполагает, что его истинное значение — истинно. Исключение составляет '0', значение которого всегда ложно.

QDoc будет распознавать и может оценивать следующий синтаксис препроцессора:

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

Однако, столкнувшись с неизвестным синтаксисом, например

#if NOTYET
    ...
#endif

QDoc по умолчанию будет оценивать его как истинное, за исключением случаев, когда символ препроцессора указан в записи переменной falsehoods:

falsehoods = NOTYET

См. также defines.

generateindex

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

По умолчанию файл индекса всегда генерируется с HTML-документацией, поэтому эта переменная обычно используется только для отключения этой функции (установкой значения в false) или для включения генерации индекса для вывода WebXML (установкой значения в true).

headerdirs

Переменная headerdirs определяет каталоги, содержащие заголовочные файлы, связанные с исходными .cpp файлами, используемыми в документации.

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

При выполнении QDoc в первую очередь прочитает заголовки, указанные в переменной headers, и те, что находятся в директориях, указанных в переменной headerdir (включая все поддиректории), создавая внутреннюю структуру классов и их функций.

Затем он прочитает исходные файлы, указанные в sources, и те, что находятся в директориях, указанных в sourcedirs (включая все поддиректории), объединяя документацию со структурой, полученной из файлов заголовков.

Если переменные headers и headerdirs определены, QDoc прочитает оба файла, сначала headers, а затем headerdirs.

В указанных директориях QDoc будет читать только файлы с расширениями, указанными в headers.fileextensions переменной. По умолчанию расширения — *.ch, *.h, *.h++, *.hh, *.hpp и *.hxx". Файлы, указанные переменной headers, будут читаться без учёта их расширений.

См. также headers и headers.fileextensions.

headers

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

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

При обработке переменной headers QDoc ведет себя так же, как и при обработке переменной headerdirs. Дополнительную информацию см. в переменной headerdirs.

См. также headerdirs.

headers.fileextensions

Переменная headers.fileextensions указывает расширение, используемое для файлов заголовков.

При обработке файлов заголовков, указанных в headerdirs переменной, QDoc будет читать только те файлы, у которых расширение указано в переменной headers.fileextensions. Таким образом, QDoc избегает траты времени на чтение не относящихся к делу файлов.

По умолчанию расширения — *.ch, *.h, *.h++, *.hh, *.hpp и *.hxx.

Расширения задаются как стандартные выражения подстановок. Вы можете добавить расширение к фильтру, используя '+='. Например:

header.fileextensions += *.H

Предупреждение: вышеуказанное присваивание может работать не так, как описано.

См. также headerdirs.

imagedirs

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

Переменные images и imagedirs используются командами \image и \inlineimage. Если переменные images и imagedirs определены, QDoc будет искать в обоих. Сначала в images, затем в imagedirs.

QDoc будет искать в директориях в указанном порядке и принимать первый найденный соответствующий файл. Он будет искать только в указанных директориях, не в поддиректориях.

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

При обработке

\image calculator-example.png

QDoc проверит, есть ли файл с именем calculator-example.png, указанный как значение в переменной images. Если нет, он будет искать в переменной imagedirs файл с именем:

$QTDIR/doc/src/images/calculator-example.png

Если файл не существует, QDoc будет искать файл с именем

$QTDIR/examples/calculator-example.png

Вы можете фильтровать изображения в директории изображений, используя переменную images.fileextensions. Основная идея переменной images.fileextensions — разрешить использование разных форматов изображений для разных форматов вывода.

Предупреждение: функциональность переменной images.fileextensions предварительная, так как QDoc в настоящее время поддерживает только HTML.

См. также images и images.fileextensions.

images

Переменная images позволяет указать отдельные файлы изображений помимо тех, которые находятся в директориях, указанных переменной imagedirs.

images = $QTDIR/doc/src/images/calculator-example.png

При обработке переменной images QDoc ведет себя так же, как и при обработке imagedirs переменной. Дополнительную информацию см. в imagedirs переменной.

См. также imagedirs и images.fileextensions.

images.fileextensions

Переменная images.fileextensions фильтрует файлы в директории изображений.

Значения переменной (расширения) задаются стандартными выражениями подстановок. Общий синтаксис: images.fileextensions.format = *.extension.

Идея состоит в том, чтобы разрешить разные форматы изображений для разных форматов вывода.

images.fileextensions.HTML = *.png
images.fileextensions.LOUT = *.eps

Затем, при обработке команд \image и \inlineimage, QDoc будет искать только файлы с расширениями, указанными в переменной, содержащей список форматов вывода.

Предупреждение: это предварительная функциональность, так как QDoc в настоящее время поддерживает только HTML.

По умолчанию для HTML расширения — *.png, *.jpg, *.jpeg и *.gif.

Вы можете добавить расширение к фильтру, используя '+='. Например:

images.fileextensions.HTML += *.eps

См. также imagedirs и images.

language

Переменная language указывает язык исходного кода, используемого в документации.

В настоящее время QDoc понимает только язык C++. Это также язык по умолчанию, и его фактически не нужно указывать. Однако, вот пример объявления переменной языка:

language = Cpp

Это определяет C++ как язык Qt исходного кода.

macro

Переменная macro используется для создания собственных простых команд QDoc. Синтаксис: macro.command = definition, где определение написано с использованием синтаксиса QDoc.

Переменная макроса может быть ограничена для использования в одном типе генерации вывода. Добавление .HTML к имени макроса, например, делает макрос используемым только при генерации HTML вывода. Добавление .DITAXML к имени макроса, делает макрос используемым только при генерации DITA XML.

macro.gui              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

Первый макрос определяет команду \gui для отображения её аргумента жирным шрифтом. Второй макрос определяет команду \raisedaster для отображения символа звездочки в верхнем индексе, но только при генерации HTML.

Макрос также может принимать до семи параметров:

macro.hello            = "Hello \1!"

Параметры передаются макросам так же, как и другим командам:

\hello World

При использовании более одного параметра или когда аргумент содержит пробелы, заключите каждый аргумент в фигурные скобки:

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

См. также alias.

manifestmeta

Переменная manifestmeta указывает дополнительное мета-содержимое для файлов манифеста примера, генерируемых QDoc.

См. раздел Manifest Meta Content для получения дополнительной информации.

naturallanguage

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

naturallanguage = zh-Hans

По умолчанию естественный язык — en для совместимости со старой документацией.

qdoc добавит информацию о естественном языке в генерируемый HTML, используя атрибуты lang и xml:lang.

См. также sourceencoding, outputencoding, C.7. Атрибуты lang и xml:lang и Лучшая практика 13: Использование кодов Hans и Hant.

navigation

Подпеременные navigation, если определены, устанавливают главную страницу, стартовую страницу, страницу классов C++ и страницу типов QML, которые видны в генерированной навигационной панели для каждой страницы.

В проекте с несколькими подпроектами (например, модулями Qt), каждый подпроект обычно определяет свою собственную стартовую страницу, а одна главная страница используется во всех подпроектах.

Подпеременные

Например:

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

Вышеуказанная конфигурация создает следующую навигационную панель для Item типа QML:

Qt 5.10 > Qt Quick > QML Types > Item QML Type

outputdir

Переменная outputdir задаёт директорию, в которую QDoc поместит сгенерированную документацию.

outputdir = $QTDIR/doc/html

располагает сгенерированную документацию Qt по ссылке $QTDIR/doc/html. Например, документация класса QWidget расположена в

$QTDIR/doc/html/qwidget.html

Сопутствующие изображения будут помещены в поддиректорию images.

Предупреждение: При многократном запуске QDoc с одним и тем же выходным каталогом все файлы из предыдущего запуска будут потеряны.

outputencoding

Переменная outputencoding задаёт кодировку, используемую для генерируемой qdoc документации.

outputencoding = UTF-8

По умолчанию кодировка вывода ISO-8859-1 (Latin1) для совместимости со старой документацией. При генерации документации для некоторых языков, особенно неевропейских языков, этого недостаточно, и требуется кодировка, такая как UTF-8.

qdoc будет кодировать HTML с использованием этой кодировки и генерировать правильные объявления, чтобы указать браузерам используемую кодировку. Переменная конфигурации naturallanguage также должна быть указана, чтобы предоставить браузерам полный набор информации о кодировке символов и языке.

См. также outputencoding и naturallanguage.

outputformats

Переменная outputformats задаёт формат(ы) генерируемой документации.

Начиная с Qt 5.11, QDoc поддерживает форматы HTML и WebXML. Если не указаны outputformats, QDoc генерирует документацию в формате HTML (по умолчанию). Оба формата вывода могут быть указаны с выделенными выходными каталогами и другими настройками. Например:

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

Это генерирует документацию HTML с использованием параметров по умолчанию, а также документацию WebXML в подкаталог webxml.

outputprefixes

Переменная outputprefixes задаёт отображение между типами файлов и префиксов, добавляемых к именам HTML-файлов в сгенерированной документации.

outputprefixes     = QML JS
outputprefixes.QML = uicomponents-
outputprefixes.JS  = uicomponents-

По умолчанию файлы, содержащие документацию API для типов QML, снабжаются префиксом "qml-", а для типов javaScript - "js-". В приведённом примере вместо этого используется префикс "uicomponents" для обоих.

Префикс вывода применяется к именам файлов для документации по типам QML и JS.

outputsuffixes

Переменная outputsuffixes задаёт отображение между типами файлов и суффиксов имён модулей, которые добавляются к именам HTML-файлов.

outputsuffixes     = QML
outputsuffixes.QML = -tp

При именовании QML-модуля FooBar и стандартном префиксе output prefix ("qml-"), имя файла сгенерированной HTML-страницы для типа QML FooWidget будет qml-foobar-tp-foowidget.html.

По умолчанию суффикс не используется. Суффикс вывода, если он определён, применяется к именам файлов для документации по типам QML и JS, а также к страницам их соответствующих модулей.

Переменная outputsuffixes была добавлена в QDoc 5.6.

qhp

Переменная qhp используется для определения информации, которая должна быть записана в файлы проекта Qt Help (qhp)

См. главу Создание файлов проекта справки для получения информации об этом процессе.

sourcedirs

Переменная sourcedirs задаёт директории, содержащие файлы .cpp или .qdoc используемые в документации.

sourcedirs  += .. \
               ../../../examples/gui/doc/src

При выполнении QDoc, первое, что он делает, это просматривает заголовки, указанные в переменной header, и те, которые находятся в директориях, указанных в переменной headerdir (включая все подкаталоги), создавая внутреннюю структуру классов и их функций.

Затем он просматривает источники, указанные в sources, и те, которые находятся в директориях, указанных в переменной sourcedirs (включая все подкаталоги), объединяя документацию со структурой, полученной из файлов заголовков.

Если переменные sources и sourcedirs определены, QDoc прочитает обе, сначала sources, затем sourcedirs.

В указанных директориях QDoc будет читать только файлы с расширениями, указанными в sources.fileextensions переменной. Расширения по умолчанию - *.c++, *.cc, *.cpp и *.cxx. Файлы, указанные в sources, будут читаться независимо от их расширения.

См. также sources и sources.fileextensions.

sourceencoding

Переменная sourceencoding задаёт кодировку, используемую для исходного кода и документации.

sourceencoding = UTF-8

По умолчанию кодировка исходного кода ISO-8859-1 (Latin1) для совместимости со старой документацией. Для некоторых языков, особенно неевропейских языков, этого недостаточно, и требуется кодировка, такая как UTF-8.

Хотя qdoc будет использовать кодировку для чтения файлов исходного кода и документации, ограничения компиляторов C++ могут помешать вам использовать не-ASCII символы в комментариях исходного кода. В таких случаях можно написать всю документацию API в файлах документации.

См. также naturallanguage и outputencoding.

sources

Переменная sources позволяет вам указывать отдельные файлы исходного кода помимо тех, которые находятся в директориях, указанных переменной sourcedirs.

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

При обработке переменной sources, QDoc ведёт себя так же, как при обработке переменной sourcedirs. Подробнее см. переменную sourcedirs.

См. также sourcedirs.

sources.fileextensions

Переменная sources.fileextensions фильтрует файлы в директории исходного кода.

При обработке файлов исходного кода, указанных в sourcedirs, QDoc будет читать только файлы с расширениями, указанными в переменной sources.fileextensions. Таким образом, QDoc избегает траты времени на чтение нерелевантных файлов.

Расширения по умолчанию - *.c++, *.cc, *.cpp и *.cxx.

Расширения задаются стандартными выражениями подстановки. Вы можете добавить расширение файла к фильтру, используя '+='. Например:

sources.fileextensions += *.CC

Предупреждение: Приведённое выше присвоение может не работать как описано.

См. также sourcedirs и sources.

spurious

Переменная spurious исключает указанные предупреждения QDoc из вывода. Предупреждения задаются с помощью стандартных выражений подстановки.

spurious = "Cannot find .*" \
"Missing .*"

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

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

Переменная syntaxhighlighting задаёт, должен ли QDoc выполнять подсветку синтаксиса исходного кода, цитируемого в документации, которую он генерирует.

syntaxhighlighting = true

включит подсветку синтаксиса для всех поддерживаемых языков программирования.

tabsize

Переменная tabsize определяет размер символа табуляции.

tabsize = 4

присвоит символу табуляции размер в 4 пробела. Значение по умолчанию для переменной равно 8 и не обязательно для указания.

tagfile

Переменная tagfile задаёт файл тегов Doxygen, который должен быть записан при генерации HTML.

version

Переменная version задаёт номер версии документируемого программного обеспечения.

version = 5.6.0

Когда номер версии задаётся (с помощью переменных version или versionsym в файле .qdocconf), он доступен через соответствующую команду \version для использования в документации.

Предупреждение: Функциональность команды \version не полностью реализована; в настоящее время она работает только внутри кода raw HTML.

См. также versionsym.

versionsym

Переменная versionsym задаёт символ препроцессора C++, определяющий номер версии документированного программного обеспечения.

versionsym = QT_VERSION_STR

QT_VERSION_STR определяется в qglobal.h следующим образом

#define QT_VERSION_STR   "4.0.1"

При указании номера версии (с помощью переменных version или versionsym в файле .qdocconf), он доступен через соответствующую команду \version для использования в документации.

Предупреждение: Функциональность команды \version не полностью реализована. В настоящее время она работает только внутри кода обычного HTML.

См. также \version.

warninglimit

Переменная warninglimit задаёт максимальное количество разрешённых предупреждений документации. Если это ограничение превышено, QDoc продолжает работу в обычном режиме, но завершается с числом предупреждений в качестве кода ошибки. Если предел не был превышен или warninglimit не определён, процесс QDoc завершается с кодом 0, предполагая отсутствие других критических ошибок.

Установка warninglimit в 0 означает ошибку при любом предупреждении.

Примечание: По умолчанию QDoc не применяет ограничение на количество предупреждений. Включите его с помощью warninglimit.enabled = true или, определив переменную окружения QDOC_ENABLE_WARNINGLIMIT.

Например,

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

Переменная warninglimit была добавлена в Qt 5.11.