From 1e47a9594cae0240bcc9dfb615dea5639e6e65d2 Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Fri, 9 Aug 2013 12:55:08 +0200 Subject: Doc: qtgui configuration file with comments Task-number: QTBUG-31801 Change-Id: I225edf67f586cc5822269c643020d5666465712d Reviewed-by: Martin Smith Reviewed-by: Jerome Pasion --- src/tools/qdoc/doc/qtgui-qdocconf.qdoc | 292 +++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 src/tools/qdoc/doc/qtgui-qdocconf.qdoc (limited to 'src/tools/qdoc/doc/qtgui-qdocconf.qdoc') diff --git a/src/tools/qdoc/doc/qtgui-qdocconf.qdoc b/src/tools/qdoc/doc/qtgui-qdocconf.qdoc new file mode 100644 index 0000000000..7e6da0feb5 --- /dev/null +++ b/src/tools/qdoc/doc/qtgui-qdocconf.qdoc @@ -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. +*/ -- cgit v1.2.3