AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: Document example manifest files in QDoc manual

Browse Source 
Adds documentation for example manifest files and the related qdoc
configuration command \manifestmeta into QDoc manual.

Change-Id: I6a627698ab14f57c9a117b6d4b794f352959f5ac
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
This commit is contained in:
Topi Reinio 2013-02-18 13:55:37 +01:00 committed by The Qt Project
parent c90626f189
commit a595ac15cd
1 changed files with 93 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
src/tools/qdoc/doc/qdoc-manual.qdoc
View File

@ -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
<?xml version="1.0" encoding="UTF-8"?>
<instructionals module="QtGui">
<examples>
<example
name="Analog Clock Window Example"
docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html"
projectPath="gui/analogclock/analogclock.pro"
imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window-example.png">
<description><![CDATA[The Analog Clock Window example shows how
to draw the contents of a custom window.]]></description>
<tags>analog,clock,window</tags>
<fileToOpen>gui/analogclock/main.cpp</fileToOpen>
</example>
...
</examples>
</instructionals>
\endcode
Each \c {<example>} 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