Doc: qtgui configuration file with comments
Task-number: QTBUG-31801 Change-Id: I225edf67f586cc5822269c643020d5666465712d Reviewed-by: Martin Smith <martin.smith@digia.com> Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
This commit is contained in:
Nico Vertriest
The Qt Project
parent
54f1d7e2e4
commit
1e47a9594c
292
src/tools/qdoc/doc/qtgui-qdocconf.qdoc
Normal file
292
src/tools/qdoc/doc/qtgui-qdocconf.qdoc
Normal file
@ -0,0 +1,292 @@
|
||||
/****************************************************************************
|
||||
**
|
||||
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
|
||||
** Contact: http://www.qt-project.org/legal
|
||||
**
|
||||
** This file is part of the documentation of the Qt Toolkit.
|
||||
**
|
||||
** $QT_BEGIN_LICENSE:FDL$
|
||||
** Commercial License Usage
|
||||
** Licensees holding valid commercial Qt licenses may use this file in
|
||||
** accordance with the commercial license agreement provided with the
|
||||
** Software or, alternatively, in accordance with the terms contained in
|
||||
** a written agreement between you and Digia. For licensing terms and
|
||||
** conditions see http://qt.digia.com/licensing. For further information
|
||||
** use the contact form at http://qt.digia.com/contact-us.
|
||||
**
|
||||
** GNU Free Documentation License Usage
|
||||
** Alternatively, this file may be used under the terms of the GNU Free
|
||||
** Documentation License version 1.3 as published by the Free Software
|
||||
** Foundation and appearing in the file included in the packaging of
|
||||
** this file. Please review the following information to ensure
|
||||
** the GNU Free Documentation License version 1.3 requirements
|
||||
** will be met: http://www.gnu.org/copyleft/fdl.html.
|
||||
** $QT_END_LICENSE$
|
||||
**
|
||||
****************************************************************************/
|
||||
|
||||
/*!
|
||||
|
||||
\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 qtgui.qdocconf. The subsequent section will discuss
|
||||
every statement in the qdocconf file.
|
||||
|
||||
\code
|
||||
include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
|
||||
|
||||
project = QtGui
|
||||
description = Qt GUI Reference Documentation
|
||||
url = http://qt-project.org/doc/qt-$QT_VER/qtgui
|
||||
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.filterAttributes = qtgui $QT_VERSION qtrefdoc
|
||||
qhp.QtGui.customFilters.Qt.name = Qtgui $QT_VERSION
|
||||
qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION
|
||||
|
||||
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 fake:headerfile
|
||||
qhp.QtGui.subprojects.classes.sortPages = true
|
||||
|
||||
tagfile = ../../../doc/qtgui/qtgui.tags
|
||||
|
||||
depends += \
|
||||
qtcore \
|
||||
qtnetwork \
|
||||
qtopengl \
|
||||
qtsvg \
|
||||
qtqml \
|
||||
qtquick \
|
||||
qtwidgets \
|
||||
qtdoc
|
||||
|
||||
headerdirs += ..
|
||||
|
||||
sourcedirs += .. \
|
||||
../../../examples/gui/doc/src
|
||||
|
||||
exampledirs += ../../../examples/gui \
|
||||
snippets
|
||||
|
||||
imagedirs += images \
|
||||
../../../examples/gui/doc/images \
|
||||
../../../doc/src/images \
|
||||
\endcode
|
||||
|
||||
\title Qtgui.qdocconf with notes
|
||||
|
||||
\code
|
||||
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.
|
||||
\code
|
||||
qmake -query
|
||||
\endcode
|
||||
|
||||
\sa include
|
||||
|
||||
\code
|
||||
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.
|
||||
|
||||
\sa project
|
||||
|
||||
\code
|
||||
description = Qt GUI Reference Documentation
|
||||
\endcode
|
||||
|
||||
A short description of the project concerned.
|
||||
|
||||
\code
|
||||
url = http://qt-project.org/doc/qt-$QT_VER/qtgui
|
||||
\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 links
|
||||
to content listed in the index.
|
||||
|
||||
\note QDoc omits this value when the -installdir argument
|
||||
is specified when running QDoc.
|
||||
|
||||
\keyword examplesinstallpath
|
||||
|
||||
\code
|
||||
examplesinstallpath = gui
|
||||
\endcode
|
||||
|
||||
This \e 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 exampledirs.
|
||||
\sa exampledirs
|
||||
|
||||
\code
|
||||
qhp.projects = QtGui
|
||||
qhp.QtGui.file = qtgui.qhp
|
||||
\endcode
|
||||
|
||||
The following parameters are for creating a QHP file (\e .qhp). The qhelpgenerator
|
||||
program can convert the QHP file into a QCH file (\e .qch), which can be opened in
|
||||
Qt Assistant or Qt Creator.
|
||||
|
||||
\code
|
||||
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.
|
||||
|
||||
\code
|
||||
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 '/'.
|
||||
|
||||
\code
|
||||
qhp.QtGui.indexTitle = Qt GUI the title of the page that has the contents
|
||||
\endcode
|
||||
|
||||
This is the title of the page that has the contents.
|
||||
|
||||
\code
|
||||
qhp.QtGui.indexRoot = to be checked
|
||||
\endcode
|
||||
|
||||
Specifies the title of the root (namespace) page to generate the documentation for.
|
||||
Typically defined as an empty string.
|
||||
|
||||
\code
|
||||
qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc
|
||||
qhp.QtGui.customFilters.Qt.name = QtGui $QT_VERSION
|
||||
qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION
|
||||
\endcode
|
||||
|
||||
The documentation set (one per QDoc project) can have any number of filter
|
||||
attributes assigned to it. A filter attribute is an ordinary string which
|
||||
can be freely chosen. Additionally, custom filters that reference above
|
||||
attributes can be defined. Qt Assistant will display the name of the custom
|
||||
filter in its \gui{Filtered by} drop-down list. Only the documentation sets
|
||||
that have their filter attributes match the attributes of the selected
|
||||
custom filter will be shown.
|
||||
|
||||
\code
|
||||
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".
|
||||
|
||||
\code
|
||||
qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
|
||||
\endcode
|
||||
|
||||
Lists all headerfiles.
|
||||
|
||||
A ‘fake’ type specifies a generic documentation node, and is followed by
|
||||
a c\ : and a \e subtype specifier.
|
||||
|
||||
Possible values:
|
||||
\code
|
||||
example
|
||||
headerfile
|
||||
file
|
||||
group
|
||||
module
|
||||
page
|
||||
externalpage
|
||||
qmlclass
|
||||
qmlpropertygroup
|
||||
qmlbasictype
|
||||
\endcode
|
||||
|
||||
tagfile = ../../../doc/qtgui/qtgui.tags
|
||||
This specifies the Doxygen tag file that needs to be written when the html is generated
|
||||
by QDoc.
|
||||
|
||||
\code
|
||||
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.
|
||||
|
||||
\code
|
||||
headerdirs += ..
|
||||
\endcode
|
||||
|
||||
Add the parent directory to the list of directories containing the header files
|
||||
associated with the \e .cpp source files.
|
||||
|
||||
\code
|
||||
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.
|
||||
|
||||
\code
|
||||
exampledirs += ../../../examples/gui \
|
||||
snippets
|
||||
\endcode
|
||||
\sa examplesinstallpath
|
||||
|
||||
Add the two directories specified to the list of directories containing the source
|
||||
code of the example files.
|
||||
|
||||
\code
|
||||
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.
|
||||
*/
|
||||
Loading…
x
Reference in New Issue
Block a user