1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
QUIP: 21
Title: Using images in Qt documentation
Author: Leena Miettinen
Status: Active
Type: Process
Created: 2023-11-13
Post-History: https://lists.qt-project.org/pipermail/development/2023-November/044706.html
Overview
========
You can use the following types of images in Qt documentation:
- Screenshots
- Line diagrams
- Icons
- Animated images
- Embedded YouTube videos
Saving images
=============
QDoc can create references to images of any format. The image is shown if
the user's tool or browser supports the image format. Most browsers support the
following image formats:
- GIF (``.gif``)
- JPEG (``.jpg``)
- WebP (``.webp``)
- PNG (``.png``)
- SVG (``.svg``)
You can find reasons for picking a particular image format in the following
sections.
Locations
---------
Save images in the Git repositories in an ``images`` folder. QDoc looks for
images in folders that you specify as values of the ``imagedirs`` variable [0]_
in the documentation configuration file (``.qdocconf``).
You can create subfolders for particular types of images, such as icons or
images used in examples.
Considerations
--------------
Binary images can easily add megabytes to the Git history. To keep the history as
small as possible, the Git post-commit hooks remind you to try to keep image file
size below 50 KiB. To achieve this goal, crop images so that only relevant
information is visible.
When possible, save images in WebP format for a smaller image file size.
If you need to use the PNG format, optimize the images by using an image
optimization tool, such as ``optipng``. Optimization should not visibly
reduce image quality in the built documentation. If it does, save the
image as WebP or JPEG instead.
QDoc commands and macros
========================
Use QDoc commands to refer to images from the text:
- ``\image`` places the image on a separate line [1]_
- ``\inlineimage`` places the image inline, surrounded by text [2]_
- ``\youtube`` embeds a video from YouTube [3]_
Screenshots
===========
Qt tools, such as Qt Creator and Qt Design Studio, have the native look and feel
on Windows, Linux, and macOS. Therefore, screenshots can end up looking very
different depending on who takes them and which operating system they use.
Try to take the screenshots on one operating system, when possible.
Follow these guidelines when taking screenshots:
- Use the screen resolution of 1920x1080.
(Available on the most commonly used screens, as of this writing.)
- Use display scaling 100%.
- Use your favorite tool to take the screenshot.
- Include only the part of the screen that you need.
(You can crop the image also in the screen capture tool).
- Close all unnecessary views to avoid clutter.
- Do not scale or resize the images in the tool because it causes
reduced visual quality and increases the file size. Also, the CSS we use
online scales down images that are wider than 800 pixels.
- To highlight parts of the screenshot, use the images of numbers
that are stored in [4]_.
- If you use PNG images, optimize them before you submit them to the repository.
Note: Do not rely on screenshots to present reasonable example values to
users, but always place example values also in the text.
Note: The selected screen resolution is a compromise that offers acceptable
quality with acceptable image file size. We are looking for solutions to using
high-DPI images [5]_.
Highlighting parts of the screen
---------------------------------
You can use number icons in screenshots to highlight parts of the screenshot
(instead of using arrows or borders, for example). You can then refer to the
numbers in text. For example, see [6]_.
This improves the consistency of the look and feel of Qt documentation,
and eliminates the need to describe parts of the UI in the text because
you can just insert the number of the element you are referring to in
brackets.
You can find images of numbers from 1 to 10 in [4]_.
To use the numbers, copy-paste the number images on the screenshot to the
places that you want to refer to from text.
Icons
=====
You can view Qt Documentation online [7]_ in dark and light modes. To make the
icons used in the docs visible in both modes, save icon files as gray-scale
images with a transparent background.
If you receive a large number of icons that are not visible in either light
or dark mode or have a solid background, run the ``recolordocsicons.py``
Python script from the ``qttools/util/recolordocsicons`` folder. For options
and examples, see [8]_.
Animated images
===============
Sometimes, it is easier to explain how something works by recording a short
animation in lossless WebP or GIF format. You can use any tool you like, such
as the screen recorder in Qt Creator [9]_ or ScreenToGif [10]_. Animated images
are typically bigger than screenshots, so try to make them as short and to the
point as you can.
Use the ``\image`` command [1]_ to refer to WebP and GIF files from the
documentation.
Note: If the animation is very long, consider recording a video and embedding
it from YouTube.
YouTube videos
==============
You can use the ``\youtube`` macro [3]_ to embed a YouTube video in the HTML.
When QDoc generates offline documentation (``.qch``), it adds an external
link to the video with a thumbnail image.
References
==========
.. [0] https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#imagedirs
.. [1] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#image-command
.. [2] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#inlineimage-command
.. [3] ``macro.youtube`` in ``qtbase/doc/global/macros.qdocconf``
.. [4] ``qtdoc/doc/images/numbers/``
.. [5] https://bugreports.qt.io/browse/QTBUG-63366
.. [6] https://doc.qt.io/qtcreator/creator-quick-tour.html
.. [7] https://doc.qt.io/
.. [8] ``qttools/util/recolordocsicons/README.md``
.. [9] https://doc.qt.io/qtcreator/creator-how-to-record-screens.html
.. [10] https://www.screentogif.com/
|
