Documentation Style for 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
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
[[Category:Writing Guidelines]]
This page is obsolete and deprecated. For Qt 6 equivalent, see [[Writing Example Documentation and Tutorials]]
[[Category:Developing Qt::Examples]]
{{LangSwitch}}
This page is part of the [[Qt Writing Guidelines]].
See also:
#[[Qt6/Example-Guideline]] - Writing example code
 
 
Qt documentation follows the Qt Project's [https://contribute.qt-project.org/quips QUIP] policy system.
 
In particular, '''QUIP-13''' specifies the construction of the example, how to name the files, and other conventions that examples should follow.
 
This wiki adds more information about documenting the examples and about the minimum set of information for writing example documentation and tutorials.
 
* [https://contribute.qt-project.org/quips/13 QUIP-13] '''Qt Examples'''
 
Qt Documentation includes example documentation and tutorials. '''QDoc''' is the tool in Qt for writing, generating, and publishing documentation. For starters, familiarize yourself to the QDoc manual and the Qt Writing Guidelines.
 
* [https://doc.qt.io/qt-6/qdoc-index.html QDoc Manual]
* [[QDocExamples|Integrating Examples]]
 
==Example Documentation and Tutorials==
 
Qt 6 examples have an accompanying '''example documentation'''. This documentation should describe the example's themes and which Qt modules or tools are used. An accompanying image is important to show UI related elements and the expected output should be clear.
 
A '''tutorial''' goes beyond a description, outlining particular steps and highlighting the important parts of the example. The tutorial should ''walk through'' the code and gloss over topics related to Qt. Notes and other information should supplement the walk-through, giving insight and reason for the particular code.
 
Essentially, the '''minimum example documentation''' should contain:
 
# Example page - QDoc's '''\example''' command creates the example page. The \example command specifies the directory.
# Title - QDoc's '''\title''' command. The title should be simple and descriptive
# Brief description - '''\brief''' command and a small description of the example's theme
# Example category - label the example documentation with '''\examplecategory''' to assign it to a membership. For example ''Connectivity'', ''Desktop'', and so on.
# Main body - one or several paragraphs that describe the example's themes and expected behavior
# Running instruction - describe where to find the example (see '''Sample Text: Running Instruction''' section below)
# References - add links to related documentation, overview, or other supplementary material
# Licenses - add the '''Commercial/BSD 3 clause license (example code)''' or the '''Commercial/GFDL 1.3 (documentation files)'''
# Image - especially useful for GUI related examples. Qt Creator can show these images as thumbnails.
 
 
The '''minimum tutorial''' fulfills the minimum example documentation, and the following:
 
#Code snippets - show and analyze the code in a granular (line-by-line) or holistic (the principle and goal) way.
#Step-by-step instruction - show the progression from start to finish. A similar style is meal recipes, but do not follow strictly.
#Insight - provide insight to the code structure and Qt usage. A possible reason may be code security, scalability, usability, and so on.
#Verb-focused title - Emphasize the action or verb in the title. Use the '''gerund''', typically ending in ''-ing.'' For example, ''drawing'', ''integrating'', ''handling'', ''processing'', ''and so on.''
 
 
'''The sections below provide sample text for the requirements for example documentation and tutorial'''
 
=== Sample Text: Running Instruction ===
Example documentation and tutorials should outline the requirements and steps for building and running the example. Ideally, Qt Creator can open and launch the example, but some examples may need additional tools or environment.
 
We aim for consistency and the following text is appropriate to inform about running examples from within Qt Creator. Feel free to modify and adapt to the specific example.
 
At the bottom of your example documentation (same area as the '''\page''' command), add:<syntaxhighlight lang="c++" line="">
\include examples-run.qdocinc
</syntaxhighlight>
 
This will include the text (taken from qtbase/doc/global):
 
<syntaxhighlight lang="c++" line="1">
\section1 Running the Example
 
To run the example from \l{Qt Creator Manual}{Qt Creator}, open the Welcome
mode and select the example from Examples. For more information, visit
{Qt Creator: Building and Running an Example}{Building and Running an Example}.
</syntaxhighlight>
 
=== Sample Text: Licenses ===
 
Qt licenses are at the top of the each file.
 
For example code, use the '''Commercial/BSD 3 clause license''':
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
The example documentation and tutorial can be under a specific '''Commercial/GFDL 1.3''' documentation license:
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
== Adding Images ==
Images are useful for demonstrating UI elements and for showing the current state of the example.
 
Follow QUIP-21 for the policy for images.
 
* [https://contribute.qt-project.org/quips/21 QUIP-21] - '''Using images in Qt documentation'''
 
== Examples ==
Here are recent examples that demonstrate how to write a tutorial.
 
* [https://doc.qt.io/qt-6/qtquickcontrols-filesystemexplorer-example.html File System Explorer]
* [https://doc.qt.io/qt-6/qtdoc-demos-calqlatr-example.html Calqlatr]

Latest revision as of 15:25, 20 November 2024

This page is obsolete and deprecated. For Qt 6 equivalent, see Writing Example Documentation and Tutorials

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