diff options
Diffstat (limited to 'src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc')
| -rw-r--r-- | src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc | 296 |
1 files changed, 191 insertions, 105 deletions
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc index 226c107e3a..2472b0f4fb 100644 --- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc @@ -69,14 +69,14 @@ you to use special characters like '=' and ' \" ' within the value string, for example: - \code + \badcode HTML.postheader = "<a href=\"index.html\">Home</a>" \endcode If an entry spans many lines, use a backslash at the end of every line but the last: - \code + \badcode sourcedirs = kernel \ tools \ widgets @@ -113,6 +113,8 @@ \li \l {manifestmeta-variable} {manifestmeta} \li \l {outputdir-variable} {outputdir} \li \l {outputformats-variable} {outputformats} + \li \l {outputprefixes-variable} {outputprefixes} + \li \l {outputsuffixes-variable} {outputsuffixes} \li \l {sourcedirs-variable} {sourcedirs} \li \l {sources-variable} {sources} \li \l {sources.fileextensions-variable} {sources.fileextensions} @@ -161,7 +163,7 @@ The general syntax is \tt {alias.\e{original-command-name} = \e temporary-command-name}. - \code + \badcode alias.e = i \endcode @@ -198,7 +200,7 @@ for details). By default, no symbol is defined, meaning that code protected with #ifdef...#endif will be ignored. - \code + \badcode defines = Q_QDOC \ QT_.*_SUPPORT \ QT_.*_LIB \ @@ -226,7 +228,7 @@ You can also define preprocessor symbols manually on the command line using the -D option. For example: - \code + \badcode currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf \endcode @@ -249,7 +251,7 @@ The \c edition variable is always used with a particular edition name to define the modules for that edition: - \code + \badcode edition.Console = QtCore QtNetwork QtSql QtXml edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ QtDesigner QtAssistant Qt3Support QAxContainer \ @@ -263,7 +265,7 @@ {generatelist} command is used to generate a list of classes for this edition: - \code + \badcode \generatelist{classesbyedition Console} \endcode @@ -286,7 +288,7 @@ and accept the first matching file it finds. It will only search in the specified directories, \e not in subdirectories. - \code + \badcode exampledirs = $QTDIR/doc/src \ $QTDIR/examples \ $QTDIR \ @@ -297,7 +299,7 @@ When processing - \code + \badcode \quotefromfile widgets/calculator/calculator.cpp \endcode @@ -306,13 +308,13 @@ there isn't, it will search in the \c exampledirs variable, and first see if there exists a file called - \code + \badcode $QTDIR/doc/src/widgets/calculator/calculator.cpp \endcode If it doesn't, QDoc will continue looking for a file called - \code + \badcode $QTDIR/examples/widgets/calculator/calculator.cpp \endcode @@ -343,7 +345,7 @@ exampledirs} command. But note that if you know the file is listed in the \c examples variable, you don't need to specify its path: - \code + \badcode \quotefromfile calculator.cpp \endcode @@ -362,7 +364,7 @@ The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: - \code + \badcode examples.fileextensions += *.qrc \endcode @@ -378,7 +380,7 @@ For example: - \code + \badcode sourcedirs = src/corelib excludedirs = src/corelib/tmp \endcode @@ -395,7 +397,7 @@ The \c excludefiles variable allows you to specify individual files that should \e{not} be processed by qdoc. - \code + \badcode excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \ $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp \endcode @@ -427,7 +429,7 @@ reason, these images are specified using the \c extraimages variable: - \code + \badcode extraimages.HTML = qt-logo \endcode @@ -468,7 +470,7 @@ preprocessor symbol is specified within the \c falsehoods variable entry: - \code + \badcode falsehoods = NOTYET \endcode @@ -494,7 +496,7 @@ the header files associated with the \c .cpp source files used in the documentation. - \code + \badcode headerdirs = $QTDIR/src \ $QTDIR/extensions/activeqt \ $QTDIR/extensions/motif \ @@ -536,7 +538,7 @@ files in addition to those located in the directories specified by the \l {headerdirs} {\c headerdirs} variable. - \code + \badcode headers = $QTDIR/src/gui/widgets/qlineedit.h \ $QTDIR/src/gui/widgets/qpushbutton.h \endcode @@ -566,7 +568,7 @@ The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: - \code + \badcode header.fileextensions += *.H \endcode @@ -590,7 +592,7 @@ and accept the first matching file it finds. It will only search in the specified directories, \e not in subdirectories. - \code + \badcode imagedirs = $QTDIR/doc/src/images \ $QTDIR/examples @@ -599,7 +601,7 @@ When processing - \code + \badcode \image calculator-example.png \endcode @@ -608,13 +610,13 @@ variable. If there isn't, it will search in the \c imagedirs variable for: - \code + \badcode $QTDIR/doc/src/images/calculator-example.png \endcode If the file doesn't exist, QDoc will look for a file called - \code + \badcode $QTDIR/examples/calculator-example.png \endcode @@ -636,7 +638,7 @@ files in addition to those located in the directories specified by the \l {imagedirs} {\c imagedirs} variable. - \code + \badcode images = $QTDIR/doc/src/images/calculator-example.png \endcode @@ -660,7 +662,7 @@ The idea is to enable different image format for different output format. - \code + \badcode images.fileextensions.HTML = *.png images.fileextensions.LOUT = *.eps \endcode @@ -679,7 +681,7 @@ You can add a file extension to the filter using '+='. For example: - \code + \badcode images.fileextensions.HTML += *.eps \endcode @@ -696,7 +698,7 @@ specified. However, a possible example of a language variable statement: - \code + \badcode language = Cpp \endcode @@ -715,7 +717,7 @@ appending \c {.DITAXML} to the macro name, the macro is only used when generating DITA XML. - \code + \badcode macro.gui = "\\b" macro.raisedaster.HTML = "<sup>*</sup>" \endcode @@ -741,7 +743,7 @@ The \c naturallanguage variable specifies the natural language used for the documentation generated by qdoc. - \code + \badcode naturallanguage = zh-Hans \endcode @@ -764,7 +766,7 @@ The \c outputdir variable specifies the directory where QDoc will put the generated documentation. - \code + \badcode outputdir = $QTDIR/doc/html \endcode @@ -772,7 +774,7 @@ $QTDIR/doc/html. For example, the documentation of the QWidget class is located in - \code + \badcode $QTDIR/doc/html/qwidget.html \endcode @@ -787,7 +789,7 @@ The \c outputencoding variable specifies the encoding used for the documentation generated by qdoc. - \code + \badcode outputencoding = UTF-8 \endcode @@ -814,21 +816,48 @@ Currently, QDoc only supports the HTML format. It is also the default format, and doesn't need to be specified. - \target outputprefixes + \target outputprefixes-variable \section1 outputprefixes The \c outputprefixes variable specifies a mapping between types of files and the prefixes to prepend to the HTML file names in the generated documentation. - \code - outputprefixes = QML + \badcode + outputprefixes = QML JS outputprefixes.QML = uicomponents- + outputprefixes.JS = uicomponents- \endcode By default, files containing the API documentation for QML types - are prefixed with "qml-". In the above example, the - prefix \c "uicomponents" is used instead. + are prefixed with "qml-", and javaScript types with "js-". In the + above example, the prefix \c "uicomponents" is used instead for + both. + + The output prefix is applied to file names for documentation on + QML and JS types. + + \target outputsuffixes-variable + \section1 outputsuffixes + + The \c outputsuffixes variable specifies a mapping between types of + files and module name suffixes to append to the HTML file names. + + \badcode + outputsuffixes = QML + outputsuffixes.QML = -tp + \endcode + + Given a QML module name \e FooBar and the default + \l {outputprefixes-variable}{output prefix} ("qml-"), the file name of + the generated HTML page for a QML type \e FooWidget would be + \c qml-foobar-tp-foowidget.html. + + By default, no suffix is used. The output suffix, if defined, is applied + to file names for documentation on QML and JS types, and their respective + module pages. + + The \c outputsuffixes variable was introduced in QDoc 5.6. \target qhp-variable \section1 qhp @@ -845,7 +874,7 @@ The \c sourcedirs variable specifies the directories containing the \c .cpp or \c .qdoc files used in the documentation. - \code + \badcode sourcedirs += .. \ ../../../examples/gui/doc/src \endcode @@ -881,7 +910,7 @@ The \c sourceencoding variable specifies the encoding used for the source code and documentation. - \code + \badcode sourceencoding = UTF-8 \endcode @@ -906,7 +935,7 @@ files in addition to those located in the directories specified by the \l {sourcedirs-variable} {sourcedirs} variable. - \code + \badcode sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ $QTDIR/src/gui/widgets/qpushbutton.cpp \endcode @@ -935,7 +964,7 @@ The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: - \code + \badcode sources.fileextensions += *.CC \endcode @@ -952,7 +981,7 @@ output. The warnings are specified using standard wildcard expressions. - \code + \badcode spurious = "Cannot find .*" \ "Missing .*" \endcode @@ -961,8 +990,8 @@ will not be part of the output when running QDoc. For example would the following warning be omitted from the output: - \code - qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name + \badcode + src/opengl/qgl_mac.cpp:156: Missing parameter name \endcode \target syntaxhighlighting @@ -972,7 +1001,7 @@ perform syntax highlighting on source code quoted in the documentation it generates. - \code + \badcode syntaxhighlighting = true \endcode @@ -984,7 +1013,7 @@ The \c tabsize variable defines the size of a tab character. - \code + \badcode tabsize = 4 \endcode @@ -1003,8 +1032,8 @@ The \c version variable specifies the version number of the documented software. - \code - version = 4.0.1 + \badcode + version = 5.6.0 \endcode When a version number is specified (using the \tt{\l version} or @@ -1023,13 +1052,13 @@ The \c versionsym variable specifies a C++ preprocessor symbol that defines the version number of the documented software. - \code + \badcode versionsym = QT_VERSION_STR \endcode QT_VERSION_STR is defined in qglobal.h as follows - \code + \badcode #define QT_VERSION_STR "4.0.1" \endcode @@ -1054,42 +1083,106 @@ \section1 Overview - Starting with Qt 4.4, Qt Assistant uses a different system for managing - Qt documentation that requires QDoc to generate inventories of files in a - format that is similar to the old style DCF format, but with additional - features. + Qt Assistant uses a system for managing Qt documentation that requires + QDoc to generate inventories of files in a format that is similar to the + old style DCF format, but with additional features. - Instead of hard-coding information about the documentation sets for Qt, QDoc allows configuration variables to be used to specify which pages are to be used in each documentation set it generates. These are specified as - subvariables of the \c qch variable with each set declared using a unique + subvariables of the \c qhp variable with each set declared using a unique identifier as a subvariable. - For example, the configuration file for the Qt documentation defines a - \c Qt documentation set by specifying information about the set as - subvariables with the \c{qhp.Qt} prefix: - - \code - qhp.Qt.file = qt.qhp - qhp.Qt.namespace = org.qt-project.qtcore.$QT_VERSION_TAG - qhp.Qt.virtualFolder = qdoc - qhp.Qt.indexTitle = Qt Reference Documentation - qhp.Qt.indexRoot = - qhp.Qt.extraFiles = classic.css images/qt-logo.png - qhp.Qt.filterAttributes = qt 4.4.0 qtrefdoc - qhp.Qt.customFilters.Qt.name = Qt 4.4.0 - qhp.Qt.customFilters.Qt.filterAttributes = qt 4.4.0 - qhp.Qt.subprojects = classes overviews examples - qhp.Qt.subprojects.classes.title = Classes - qhp.Qt.subprojects.classes.indexTitle = Qt's Classes - qhp.Qt.subprojects.classes.selectors = class - qhp.Qt.subprojects.overviews.title = Overviews - qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs - qhp.Qt.subprojects.overviews.selectors = fake:page,group,module - qhp.Qt.subprojects.examples.title = Tutorials and Examples - qhp.Qt.subprojects.examples.indexTitle = Qt Examples - qhp.Qt.subprojects.examples.selectors = fake:example - \endcode + For example, the configuration file for the Qt Quick documentation set + specifies information about the set as subvariables with the + \c{qhp.QtQuick} prefix: + + \badcode + qhp.projects = QtQuick + + qhp.QtQuick.file = qtquick.qhp + qhp.QtQuick.namespace = org.qt-project.qtquick.$QT_VERSION_TAG + qhp.QtQuick.virtualFolder = qtquick + qhp.QtQuick.indexTitle = Qt Quick + qhp.QtQuick.indexRoot = + + qhp.QtQuick.filterAttributes = qtquick $QT_VERSION qtrefdoc + qhp.QtQuick.customFilters.Qt.name = QtQuick $QT_VERSION + qhp.QtQuick.customFilters.Qt.filterAttributes = qtquick $QT_VERSION + + qhp.QtQuick.subprojects = qmltypes classes examples + + qhp.QtQuick.subprojects.qmltypes.title = QML Types + qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types + qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass + qhp.QtQuick.subprojects.qmltypes.sortPages = true + + qhp.QtQuick.subprojects.classes.title = Classes + qhp.QtQuick.subprojects.classes.title = C++ Classes + qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes + qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile + qhp.QtQuick.subprojects.classes.sortPages = true + + qhp.QtQuick.subprojects.examples.title = Examples + qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials + qhp.QtQuick.subprojects.examples.selectors = fake:example + \endcode + + The documentation set may include one or more subprojects, which are added + to the table of contents under the name specified by \c title. The page + in the documentation referred to by the \c indexTitle acts as the index page + for the subproject. The page types to list under the subproject are specified + by \c selectors. The entries are alphabetically sorted if \c sortPages is set + to \c true. + + \section2 Using Selectors + + The \c selectors property specifies which page types are listed under the + table of contents entry for a subproject. Multiple selectors can be listed, + separated by whitespace. + + \table + \header \li Selector \li Description + \row \li \c namespace \li Namespaces + \row \li \c class \li Classes + \row \li \c qmltype \li QML Types + \row \li \c qmlclass \li Alias for \c qmltype. + \row \li \c module \li C++ Modules + \row \li \c qmlmodule \li QML Modules + \row \li \c doc[:subtype] \li Documentation pages with a specified + \c subtype. Multiple subtypes can be + listed as a comma-separated list. + \row \li \c fake \li Alias for \c doc. + \row \li \c group[:groupname] \li Documentation pages for members of a + specified group, as added using the + \l {ingroup-command} + {\\ingroup} groupname command. + Multiple group names can be listed as + a comma-separated list. + (Introduced in QDoc 5.6). + \endtable + + Available subtypes for the \c doc selector: + + \table + \header \li Subtype \li Description + \row \li \c example \li Examples + \row \li \c headerfile \li Header files + \row \li \c page \li Documentation pages defined with the + \l {page-command} {\\page} command. + \endtable + + For example, the following configuration would select example pages and + pages that include the \c {\ingroup tutorials} command: + + \badcode + qhp.QtQuickControls.subprojects = examples + qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials + qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples + qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials + qhp.QtQuickControls.subprojects.examples.sortPages = true + \endcode + + \section2 Adding Table of Contents To create a table of contents for a manual, create a subproject with a \c{type} property and set it to \c{manual}. The page in the documentation @@ -1101,7 +1194,7 @@ subproject for its documentation, including all the documentation in a single manual: - \code + \badcode qhp.QtCreator.subprojects = manual qhp.QtCreator.subprojects.manual.title = Qt Creator Manual qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual @@ -1133,7 +1226,7 @@ Cpp.ignoredirectives} variables, non-standard constructs (typically macros) can result in erroneous documentation. - \code + \badcode Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ Q_DECLARE_OPERATORS_FOR_FLAGS \ Q_DECLARE_PRIVATE \ @@ -1187,7 +1280,7 @@ In \l qtgui.qdocconf: - \code + \badcode Cpp.ignoretokens = QAXFACTORY_EXPORT \ QM_EXPORT_CANVAS \ ... @@ -1250,15 +1343,12 @@ quotation marks. Note that if the value spans several lines, each line needs to be enclosed by quotation marks. - \code + \badcode HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ ... "</tr></table></div></address>" \endcode - The complete variable entry provides the standard footer of the - \l {http://doc.qt.digia.com/4.0/index.html} {Qt Reference Documentation}. - \target HTML.postheader-variable \section1 HTML.postheader @@ -1272,7 +1362,7 @@ marks. Note that if the value spans several lines, each line needs to be enclosed by quotation marks. - \code + \badcode HTML.postheader = "<table border=\"0\"..." \ ... "<img src=\"images/qt-logo.png\" \ @@ -1296,7 +1386,7 @@ marks. Note that if the value spans several lines, each line needs to be enclosed by quotation marks. - \code + \badcode HTML.style = "h3.fn,span.fn" \ "{ margin-left: 1cm; text-indent: -1cm; }\n" \ "a:link { color: #004faf; text-decoration: none }\n" \ @@ -1307,10 +1397,6 @@ "body { background: #ffffff; color: black; }" \endcode - provides the HTML style for the \l - {http://doc.qt.digia.com/4.0/index.html} {Qt Reference - Documentation}. - \target HTML.stylesheets-variable \section1 HTML.stylesheets @@ -1322,7 +1408,7 @@ has been generated. Typically, it is only necessary to define a single stylesheet for any set of documentation; for example: - \code + \badcode HTML.stylesheets = classic.css \endcode @@ -1371,7 +1457,7 @@ Reference documentation, you need to specify the associated index file: - \code + \badcode indexes = $QTDIR/doc/html/qt.index \endcode @@ -1386,7 +1472,7 @@ The project's name is used to form a file name for the associated project's \e index file. - \code + \badcode project = QtCreator \endcode @@ -1406,7 +1492,7 @@ the base URL when constructing links to classes, functions, and other things listed in the index. - \code + \badcode project = Qt description = Qt Reference Documentation url = http://doc.qt.io/qt-4.8/ @@ -1429,7 +1515,7 @@ For example, \l qtgui.qdocconf (the configuration file for Qt) contains the following variable definitions: - \code + \badcode project = Qt description = Qt Reference Documentation url = http://doc.qt.io/qt-4.8/ @@ -1461,7 +1547,7 @@ A manifest file has the following structure: - \code + \badcode <?xml version="1.0" encoding="UTF-8"?> <instructionals module="QtGui"> <examples> @@ -1503,7 +1589,7 @@ Example: - \code + \badcode manifestmeta.filters = highlighted sql webkit global manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \ @@ -1539,7 +1625,7 @@ In your configuration file, set your \c {outputformats} variable to \c {DITAXML}, and send the output to an appropriate directory: - \code + \badcode outputdir = $QTDIR/doc/ditaxml outputformats = DITAXML \endcode @@ -1547,7 +1633,7 @@ And include these macros in your configuration file to prevent QDoc from doing some escaping that doesn't validate in XML: - \code + \badcode macro.aacute.DITAXML = "á" macro.Aring.DITAXML = "Å" macro.aring.DITAXML = "å" @@ -1571,7 +1657,7 @@ You can also set default values for some of the tags in the DITA \c {<prolog>} and \c {<metadata>} elements: - \code + \badcode dita.metadata.default.author = Qt Development Frameworks dita.metadata.default.permissions = all dita.metadata.default.publisher = Qt Project |