QDoc Examples

h1. Integrating Examples

This page is part of the Qt Writing Guidelines.

This guide discusses the best and effective ways to integrade examples into Qt 5. Though there are exceptions, following the guidelines ensures consistency, leading to easier maintenance and ensuring that the end-user accesses the content.

Overview of Elements

Qt Examples are comprised of these main elements:
* source code, including project files
* documentation, such as tutorials and example documentation
* manifest files, QDoc configuration, and highlighting specific examples

The following pages address the first two elements, therefore make sure you read them first:
* Qt Documentation Structure - where to put the source code, relative to the module
* Writing Qt Examples

QDoc and Package Configuration

Consult Qt Documentation Structure to see where you should place the source files and documentation files. Afterwards, ensure that QDoc can see the example files by checking the project's qdocconf file.

The following sections provide guidelines regarding various QDoc variables.

Examples Source Directory

The exampledirs variable sets the location where QDoc looks for examples and their documentation. Specifically, QDoc uses the exampledirs variables and the * QDoc command to find and form the page URLs for the example documentation.

For example, suppose that an example called Simple Code has the following documentation:

<br />simplecode<br />imple Code Example<br />

and consider that the exampledirs variable is set to variousexample.
QDoc then assumes that the example is in the directory variousexample/simplecode. QDoc uses this information to form the HTML pages as well.

Note: The exampledirs variable is usually set using a relative path.

Example Installation Path

Each module or QDoc project sets the examplesinstallpath variable (in .qdocconf files), which determines where the examples are located in the downloaded Qt packages.

For example, Qt Quick's install path is quick:

<br />examplesinstallpath = quick<br />

Therefore, examples in Qt Quick are installed under the quick directory. In Qt 5.3 packages, examples are in C:5.3.1\Examples\Qt-5.3\quick (when the default installation directory is used).

Thumbnail Images

Every example require a thumbnail image in the documentation. This thumbnail is then used in Qt Creator's example pages.
For non-visual examples such as command-line examples, you may bypass the thumbnail image by listing the example in the manifestmeta.thumbnail.names variable.

For example, in Qt Quick's qdocconf file:

<br />manifestmeta.thumbnail.names += &quot;QtQuick/Threaded ListModel Example&amp;quot;<br />

The Threaded ListModel Example has a generic Qt image as its thumbnail.

Note: The QtQuick/Threaded ListModel Example portion from the snippet above denotes the module name and the example title name and not the directory names.

Highlighted and Tagged Examples

To declare that an example is highlighted or for a specific platform, add the example to the manifestmeta variables. There is a master list in qtbase's doc/global/manifest-meta.qdocconf file.

Qt Creator will then display the examples and the tags in its Example mode. The user can then search for those examples using the tags.

Committing and Using Codereview

Examples have to pass the Qt CI process (see Commit_Policy) and these are some things to consider:
* Some repositories may not see the example files. Check that the examples is not in the .gitignore file.
* Check for licenses and that the code follows the Commit_Policy.