qtgui-qdocconf.qdoc

Go to the documentation of this file.

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
 
\page qtgui-qdocconf.html
\title qtgui.qdocconf with Comments
 
\brief A walkthrough of a typical qdocconf file.
 
This document goes through a typical Qt 5 qdocconf file. The contents is taken from
Qt GUI's \e qtgui.qdocconf file.
 
Below you will find the full contents of \c qtgui.qdocconf. The subsequent section will discuss
every statement in the qdocconf file.
 
\badcode
   include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
 
   project                 = QtGui
   description             = Qt GUI Reference Documentation
   url                     = http://doc.qt.io/qt
   version                 = $QT_VERSION
 
   examplesinstallpath     = gui
 
   qhp.projects            = QtGui
 
   qhp.QtGui.file         = qtgui.qhp
   qhp.QtGui.namespace           = org.qt-project.qtgui.$QT_VERSION_TAG
   qhp.QtGui.virtualFolder       = qtgui
   qhp.QtGui.indexTitle          = Qt GUI
   qhp.QtGui.indexRoot           =
 
   qhp.QtGui.subprojects         = classes
   qhp.QtGui.subprojects.classes.title = C++ Classes
   qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
   qhp.QtGui.subprojects.classes.selectors = class headerfile
   qhp.QtGui.subprojects.classes.sortPages = true
 
   tagfile                 = qtgui.tags
 
   depends += \
       qtcore \
       qtnetwork \
       qtopengl \
       qtsvg \
       qtqml \
       qtquick \
       qtwidgets \
       qtdoc
 
   headerdirs  += ..
 
   sourcedirs  += .. \
                  ../../../examples/gui/doc/src
 
   excludedirs  = ../../../examples/gui/doc/src/tmp
 
   exampledirs += ../../../examples/gui \
                  snippets
 
   imagedirs   += images \
                  ../../../examples/gui/doc/images \
                  ../../../doc/src/images
\endcode
 
\title Qtgui.qdocconf with notes
 
\badcode
   include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
\endcode
 
QDoc inherits the default templates, macros, and settings from the directory
specified from the \c $QT_INSTALL_DOCS variable. \c qmake prints the value of
the variable.
\badcode
   qmake -query
\endcode
 
\b {See also}: \l {include}.
 
\badcode
   project                 = QtGui
\endcode
 
The \c project variable sets the name of the QDoc build. This name is also
used to form the index file, which, in this case, will be \e qtgui.index. The
name of the index file doesn't adopt the uppercase letters of the project name.
 
\b {See also}: \l {project}.
 
\badcode
   description             = Qt GUI Reference Documentation
\endcode
 
A short description of the project concerned.
 
\badcode
   url                     = http://doc.qt.io/qt-5
\endcode
 
The \c url variable holds the base url of the project.
 
The URL is stored in the generated index file for the project.
QDoc will use this as the base URL when constructing external links
to content listed in the index.
 
\note QDoc omits this value when the -installdir argument
is specified when running QDoc.
 
\badcode
   examplesinstallpath     = gui
\endcode
 
The \c examplesinstallpath variable indicates that the examples will be
installed in the \e gui directory under the parent examples directory
(for Qt, this is $QT_INSTALL_EXAMPLES).
 
\note The examplepath variable has to match the example directory specified in
      \c exampledirs.
 
\note It is possible to override \c examplesinstallpath for a specific
      \l {example-command}{\\example} using the \l {meta-command}{\\meta}
      command.
 
\b {See also}: \l {examplesinstallpath}, \l {exampledirs}, and
\l {meta-command}{\\meta}.
 
\badcode
   qhp.projects    = QtGui
   qhp.QtGui.file  = qtgui.qhp
\endcode
 
The following parameters are for creating a QHP file (\e .qhp). The
\e qhelpgenerator program can convert the QHP file into a QCH file (\e .qch),
which can be opened in Qt Assistant or Qt Creator.
 
\badcode
   qhp.QtGui.namespace           = org.qt-project.qtgui.$QT_VERSION_TAG
\endcode
 
A unique identifier which enables QHelpEngine to retrieve the helpfile
from a given link. This namespace is also used as a base url for links
to the helpfile.
 
\badcode
   qhp.QtGui.virtualFolder       = qtgui
\endcode
 
Virtual folders group documentation together into a single location. A
virtual folder will become the root directory of all files referenced in
a compressed help file.
 
When two manuals are located in the same virtual folder, it is possible to
refer to sections of the other manual using relative paths. The virtual
folder tag is mandatory and the folder must not contain any '/'.
 
\badcode
   qhp.QtGui.indexTitle          = Qt GUI
\endcode
 
This is the title of the page that has the contents.
 
\badcode
   qhp.QtGui.indexRoot           =
\endcode
 
Specifies the title of the root (namespace) page to generate the documentation for.
Typically defined as an empty string.
 
\badcode
   qhp.QtGui.subprojects         = classes
   qhp.QtGui.subprojects.classes.title = C++ Classes
   qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
\endcode
The subprojects specify the sections that are displayed in the table of contents
for this project.  In this example, the subproject, which is displayed in
the Assistant's sidebar, is named "C++ Classes" and its index is the page
titled "QT GUI C++ Classes".
 
\badcode
   qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
\endcode
 
Lists all C++ classes and header files.
 
See \l {Creating Help Project Files} for more information.
 
\badcode
    tagfile                 = ../../../doc/qtgui/qtgui.tags
\endcode
 
This specifies the Doxygen tag file that needs to be written when the html is generated
by QDoc.
 
\badcode
depends += \
   qtcore \
   qtnetwork \
   qtopengl \
   qtsvg \
   qtqml \
   qtquick \
   qtwidgets \
   qtdoc
\endcode
 
Specifies the modules QDoc needs to load for generating output for Qt GUI.
QDoc loads the index files for all modules listed in the depends statement in
order to enable linking to pages in these modules.
 
\badcode
   headerdirs  += ..
\endcode
 
Add the parent directory to the list of directories containing the header files
associated with the \e .cpp source files.
 
\badcode
   sourcedirs  += .. \
                  ../../../examples/gui/doc/src
\endcode
 
Add the specified directories to the list of directories containing the \e .cpp and
\e .qdoc files used in the documentation.
 
\badcode
   excludedirs  = ../../../examples/gui/doc/src/tmp
\endcode
 
The \c excludedirs variable is for listing directories that should not be processed
by QDoc, even if the same directories are included by the \c sourcedirs or \c headerdirs
variables.
 
When executed, QDoc will ignore the directories listed.
\b {See also}: \l {excludefiles}.
 
\badcode
   exampledirs += ../../../examples/gui \
                  snippets
\endcode
\b {See also}: \l {examples-variable}{examples}, \l {examplesinstallpath}.
 
Add the two directories specified to the list of directories containing the source
code of the example files.
 
If QDoc encounters both \c exampledirs and \c examples, it will look first in the
\c examples directory.  QDoc will accept the first matching file it finds. QDoc will
search in the directories specified, not in their subdirectories.
 
\badcode
   imagedirs   += images \
                  ../../../examples/gui/doc/images \
                  ../../../doc/src/images \
\endcode
 
Add the directories specified above to the list of directories where the images
can be found.
*/