Qt LogoProject

QUIP 21: Using images in Qt documentation

by Leena Miettinen

Details

  • Number: 21
  • Title: Using images in Qt documentation
  • Author: Leena Miettinen
  • Status: Active
  • Type: Process
  • Post History: 044706.html
  • Created: 13 November 2023

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 variable1 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, or2. 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 line3
  • \inlineimage places the image inline, surrounded by text4
  • \youtube embeds a video from YouTube5

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 in6.
  • 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 images7.

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, see8.

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 in9.

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 online10 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, see11.

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 Creator12 or ScreenToGif13. Animated images are typically bigger than screenshots, so try to make them as short and to the point as you can.

Use the \image command14 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 macro15 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

Footnotes

  1. [1] https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#imagedirs ↩

  2. [2] https://qt-webassembly.io/imagetool/ ↩

  3. [3] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#image-command ↩

  4. [4] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#inlineimage-command ↩

  5. [5] macro.youtube in qtbase/doc/global/macros.qdocconf ↩

  6. [6] qtdoc/doc/images/numbers/ ↩

  7. [7] https://bugreports.qt.io/browse/QTBUG-63366 ↩

  8. [8] https://doc.qt.io/qtcreator/creator-quick-tour.html ↩

  9. [9] qtdoc/doc/images/numbers/ ↩

  10. [10] https://doc.qt.io/ ↩

  11. [11] qttools/util/recolordocsicons/README.md ↩

  12. [12] https://doc.qt.io/qtcreator/creator-how-to-record-screens.html ↩

  13. [13] https://www.screentogif.com/ ↩

  14. [14] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#image-command ↩

  15. [15] macro.youtube in qtbase/doc/global/macros.qdocconf ↩