diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc index 4d70faa968..b715b200bf 100644 --- a/src/tools/qdoc/doc/qdoc-manual.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual.qdoc @@ -65,6 +65,7 @@ \li \l {C++ Specific Configuration Variables} \li \l {HTML Specific Configuration Variables} \li \l {Supporting Derived Projects} + \li \l {Example Manifest Files} \li \l {qt.qdocconf} \li \l {minimum.qdocconf} \li \l {Generating DITA XML Output} @@ -7154,6 +7155,7 @@ \li \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions} \li \l {22-qdoc-configuration-generalvariables.html#language-variable} {language} \li \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro} + \li \l {22-qdoc-configuration-generalvariables.html#manifestmeta-variable} {manifestmeta} \li \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir} \li \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats} \li \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs} @@ -7850,6 +7852,14 @@ See also \l {alias-variable} {alias}. + \target manifestmeta-variable + \section1 manifestmeta + + The \c manifestmeta variable specifies additional meta-content + for the example manifest files generated by QDoc. + + See the \l{Manifest Meta Content} section for more information. + \target naturallanguage-variable \section1 naturallanguage @@ -8472,6 +8482,7 @@ \page 25-qdoc-configuration-derivedprojects.html \previouspage HTML Specific Configuration Variables \contentspage QDoc Manual + \nextpage Example Manifest Files \title Supporting Derived Projects @@ -8609,6 +8620,88 @@ write a new document. */ +/*! + \page 26-qdoc-configuration-example-manifest-files.html + \previouspage Supporting Derived Projects + \contentspage QDoc Manual + + \title Example Manifest Files + + QDoc generates XML files that contain information about all documented + examples and demos. These files, named \c {examples-manifest.xml} and + \c {demos-manifest.xml}, are used by Qt Creator to present a list of + examples in its welcome screen and to link to their documentation. + + \section1 Manifest XML Structure + + A manifest file has the following structure: + + \code + + + + + + analog,clock,window + gui/analogclock/main.cpp + + ... + + + \endcode + + Each \c {} element contains information about a name, + description, the location of the project file and documentation, + as well as a list of tags associated with the example. + + \target metacontent + \section1 Manifest Meta Content + + It is possible to augment the manifest files with additional + meta-content - that is, extra attributes and tags for selected + examples, using the \c manifestmeta configuration command. + + One use case for meta-content is highlighting a number of prominent + examples. Another is improving search functionality by adding + relevant keywords as tags for a certain category of examples. + + The examples for which meta-content is applied to is specified using + one or more filters. Matching examples to filters is done based on + names, with each example name prefixed with a module name and a + slash. Simple wildcard matching is supported; by using \c {*} at the + end it's possible to match multiple examples with a single string. + + Example: + + \code + manifestmeta.filters = highlighted sql webkit global + + manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \ + "QtWidgets/Analog Clock Example" + manifestmeta.highlighted.attributes = isHighlighted:true + + manifestmeta.sql.names = "QtSql/*" + manifestmeta.sql.tags = database,sql + + manifestmeta.webkit.names = "QtWebKitExamples/*" + manifestmeta.webkit.tags = webkit + + manifestmeta.global.names = * + manifestmeta.global.tags = qt5 + \endcode + + Above, an \c isHighlighted attribute is added to two examples. If + the attribute value is omitted, QDoc uses the string \c {true} by + default. Extra tags are added for Qt WebKit and Qt SQL examples, and + another tag is applied to all examples by using just \c {*} as the + match string. +*/ + /*! \page 27-qdoc-commands-alphabetical.html \previouspage Introduction to QDoc