QDoc Examples: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Redirect readers to new Qt 6 page)
Tags: Replaced Visual edit
 
Line 1: Line 1:
[[Category:Writing Guidelines]]
This page is obsolete and deprecated. For Qt 6 equivalent, see [[Contributing Examples to Qt]]
{{LangSwitch}}
This page is part of the [[QtWritingGuidelines| 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 | Qt Documentation Structure]] - where to put the source code, relative to the module
* [[ExamplesDocumentationStyle | Writing Qt Examples]]
 
== QDoc and Package Configuration ==
 
We use '''QDoc''' for writing example documentation and tutorials.
 
First, consult the [https://doc.qt.io/qt-6/qdoc-index.html 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 [https://doc.qt.io/qt-6/21-0-qdoc-configuration.html 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  :
<code>
variousexample
    simplecode
    complexcode
 
</code>
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'':
<code>
examplesinstallpath = quick
</code>
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:
<code>
manifestmeta.thumbnail.names += "QtQuick/Threaded ListModel Example"
</code>
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]] .

Latest revision as of 15:23, 20 November 2024

This page is obsolete and deprecated. For Qt 6 equivalent, see Contributing Examples to Qt

Retrieved from "https://wiki.qt.io/index.php?title=QDoc_Examples&oldid=43256"