QDoc Examples: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(Redirect readers to new Qt 6 page)
Tags: Replaced Visual edit
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Writing Guidelines]]
This page is obsolete and deprecated. For Qt 6 equivalent, see [[Contributing Examples to Qt]]
{{Cleanup|reason=QDoc commands broken by import script. Please review}}
{{LangSwitch}}
This page is part of the [[QtWritingGuidelines| 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 | Qt Documentation Structure]] - where to put the source code, relative to the module
* [[ExamplesDocumentationStyle | Writing Qt Examples]]
 
== QDoc and Package Configuration ==
 
Consult [[Qt_Documentation_Structure | 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:
<code>
simplecode
imple Code Example
</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>} to the \example part in qdoc.
 
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]].

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"