QDoc Examples

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

This page is part of the Qt Writing Guidelines.

This guide discusses the best and effective ways to integrate examples into Qt. 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:

• source code and project files so that Qt Creator can run the example
• documentation, such as tutorials and example documentation

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

We use QDoc for writing example documentation and tutorials.

First, consult the QDoc Manual and then read the Qt Documentation Structure to see where you should place the source files and documentation files.

In particular, read the section on The QDoc Configuration File

The following sections are for configuring the QDoc variables in the example's .qdocconf file.

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 a directory name called variousexample has several examples and we are setting the example called Simple Code in the simplecode directory  :

variousexample
     simplecode
     complexcode

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:

examplesinstallpath = quick

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:

manifestmeta.thumbnail.names += "QtQuick/Threaded ListModel Example"

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.

Example categories, highlighted and tagged Examples

Each example should be added to a category. You do this by adding \\meta{category}{<Category>} qdoc command in o the examples documentation.

qdoc will also generate some tags based on title and module name. To add additional tags, use the \meta {tag} {tag1, tag2 ...} qdoc command in the examples documentation.

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.

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.

Debugging

An example doesn't show up in Qt Creator welcome screen? Check out Qt Examples in Qt Creator .