Writing Documentation

When you add plugins or contribute new features to Qt Creator, you probably want other people to know about them and to be able to use them. Therefore, you should also contribute their documentation. Follow the guidelines in this section to make sure that your documentation fits in well with the rest of the Qt Creator documentation.

When you contribute a plugin, you should write documentation both for the developers who use Qt Creator and for those who develop it.

Add the following types of topics to the Qt Creator Manual or as a separate plugin manual if your plugin is located in a repository of its own:

• Overview topics, which describe the purpose of your plugin from the viewpoint of Qt Creator users.
• Tutorials, which describe how to create different types of Qt applications.
• How-to topics, which describe how to perform tasks with your plugin as part of Qt Creator.
• Reference topics, which contain information that developers occasionally need to look up.

Add the following types of topics to the Extending Qt Creator Manual:

• Overview topic, which describes the architecture and use cases for your plugin from the viewpoint of Qt Creator developers.
• API documentation, which is generated from code comments.

Configuring Documentation Projects

Use QDoc to write Qt Creator documentation. For more information about using QDoc, see the QDoc Manual.

QDoc finds the new topics automatically, when you place them as .qdoc files in a doc source folder. However, to make the topics accessible to readers:

• Add them to the table of contents in qtcreator-toc.qdoc.
• Use the \ingroup command to automatically add them to lists of topics.
• Use the \l (link) and \sa (see also) commands to add links to them from other topics.

Creating Folders and Files

The qtcreator repository contains the sources for building the following documents:

• Qt Creator Manual
• Extending Qt Creator Manual

The sources for each project are in the following subfolders of the Qt Creator project folder:

• \doc\qtcreator\src
• \doc\qtcreatordev\src

The Extending Qt Creator Manual pulls in API reference documentation from the Qt Creator source files. Add code documentation directly to the code source files. However, you can write an API overview also as a separate .qdoc file.

Create a subfolder for your documentation in the appropriate src folder. Create a separate file for each topic.

The easiest way is probably to copy an existing file, save it as a new file, and modify it. This way, you already have samples of the necessary bits and pieces in place, such as topic start and end commands, copyright statement, topic command (usually \page), navigation links, grouping, and topic title.

Integrating Topics to Documentation

You must integrate your new topics to the manuals by adding links to them from the table of contents and from other relevant topics. The easiest way to do this, is to add \ingroup commands in each topic.

In the Qt Creator Manual, you can see the current groups in the How To and Reference sections of the TOC. You can add new groups.

To link to the topics from other topics, you can use the topic title.

For example:

\l {Integrating Topics to Documentation}

\sa {Integrating Topics to Documentation}

This only works if topic titles are unique. Also, if you change the title, the link breaks. You can avoid this risk by adding the \target command to your topic and then linking to the target.

Updating Next and Previous Links

QDoc automatically generates links to the previous and next page in each manual based on the list in a topic with the title All Topics, which is in the following file: \qtcreator\doc\qtcreator\src\qtcreator-toc.qdoc.

The title of the topic to use for automatically generating the navigation links is set as the value of the navigation.toctitles option in the document configuration file: \doc\qtcreator\config\qtcreator-project.qdocconf.

When you add new topics, you must add them either to the TOC or to a group of topics (\ingroup) that is used to generate a list in the TOC (\generatelist).

Adding Documentation for Independent Plugins

You can develop Qt Creator plugins in separate repositories. Such plugins should have their own help files (.qch) that are installed and registered only if the plugin is installed.

The easiest way to set up the documentation project for an independent plugin is to copy it from an existing repository, and then make the necessary changes.

Use the following naming scheme for Qt Creator plugin manuals: Qt Creator <Plugin Name> Plugin Manual.

Writing Text

Follow the guidelines in Writing Qt Documentation.

The documentation must be grammatically correct English and use the standard form of written language. Do not use dialect or slang words. Use idiomatic language, that is, expressions that are characteristic for English. If possible, ask a native English speaker for a review.

Capitalizing Headings

Use the book title capitalization style for all titles and section headings (\title, \section1, \section2, and so on). For more information, see Using Book Style Capitalization.

Using Images

You can illustrate documentation by using screen shots, diagrams, and animated images, for example.

Follow the guidelines in QUIP 21 | Using images in Qt documentation.

The following sections contain some Qt Creator specific guidelines and examples.

Icons

The Qt Documentation published online can be viewed 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 in the following location: qtcreator/doc/qtcreator/images/icons.

You can use a script located in qttools/util/recolordocsicons/ to recolor icons.

Saving Images

Save images in PNG or WebP format in the Qt Creator project folder in the doc/qtcreator/images folder or its subfolders.

Before committing PNG images, optimize them by using an image optimization tool, such as OptiPNG. To invoke it from the Qt Creator project enter the following command:

optipng -o 7 -strip all doc/images/<screenshot_name>

Linking to Youtube Videos

You can use the \youtube macro to link to a video on Youtube. The HTML docs show a thumbnail of the video with a play button.

The support for the macro is defined in the qtcreator\doc\config\macros.qdocconf and qtcreator\doc\config\macros-online.qdocconf files. To use the macro, you need to save a thumbnail of the video in qtcreator\doc\qtcreator\images\extraimages\images.

You must add the filename of the thumbnail file to the qtcreator-extraimages.qdocconf file in the \qtcreator\doc\qtcreator\images\extraimages folder.

Building Documentation

You use QDoc to build the documentation. Build the documentation before submitting any documentation patches, to check its structure, contents, and the validity of the QDoc commands. The error messages that QDoc issues are generally very useful for troubleshooting.

Setting Up Documentation Builds

You can use an installed Qt version to build the documentation. The content and formatting of documentation are separated in QDoc. The documentation configuration, style sheets, and templates have changed over time, so they differ between Qt and Qt Creator versions.

The templates to use are defined by the qt5/qtbase/doc/global/qt-html-templates-offline.qdocconf and qt5/qtbase/doc/global/qt-html-templates-online.qdocconf configuration file. They are fetched from Qt sources by adding the following lines to the qdocconf file:

• include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf) for help files.
• include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf) for publishing on the web.

To build documentation for the sources from the qtcreator master branch, use build scripts defined in the doc.pri file. You can build the docs using either the offline or online style. The offline style is used for generating HTML files included in help files (.qch), whereas the online style is used at doc.qt.io.

Using CMake

When using CMake, the docs are built in the Qt Creator build folder or a separate doc build folder, not in the project folder.

To build docs with CMake in a separate doc build folder:

1. Create a folder for the built docs and switch to it. For example, C:\dev\qtc-doc-build.
2. In the doc build folder, enter the following command:

   cmake -DWITH_DOCS=ON "-DCMAKE_PREFIX_PATH=<path_to_qt>" <path_to_qtcreator_src>

   For example (all on one line):

   C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.10.0\msvc2022_64"
       C:\dev\qtc-super\qtcreator

3. To also build Extending Qt Creator Manual, add the following option: -DBUILD_DEVELOPER_DOCS=ON
4. To build the docs using the online style, use the following option instead of -DWITH_DOCS=ON: -DWITH_ONLINE_DOCS=ON

   For example:

   C:\dev\qtc-doc-build>cmake -DWITH_ONLINE_DOCS=ON
       -DBUILD_DEVELOPER_DOCS=ON
       -DBUILD_DESIGNSTUDIO=ON
       "-DCMAKE_PREFIX_PATH=C:\Qt\6.10.0\msvc2022_64"
       C:\dev\qtc-super\qtcreator

   Note: If you already ran CMake -DWITH_DOCS=ON in a folder and want to switch to only online docs in that folder, you need to turn the offline docs off again:

   cmake -DWITH_DOCS=OFF -DWITH_ONLINE_DOCS=ON

5. Enter the following doc build command to build both HTML docs and the help files (.qch):

   cmake --build . --target docs

6. Alternatively, to build only the HTML docs, enter:

   cmake --build . --target html_docs

The HTML files for the documentation are generated in the following folders:

• doc/html/qtcreator
• doc/html/qtcreator-dev
• doc/html/qtcreator-online
• doc/html/qtcreator-dev-online

The help files (.qch) are generated in the share/doc/qtcreator folder or in the <application_name>.app/Contents/Resources/doc\ folder on macOS.

You can view the HTML files in a browser and the help files in the Qt Creator Help mode. For more information about adding the help files to Qt Creator, see Qt Creator: Add external documentation.

Additional Build Commands

Besides docs and html_docs, you can use the following build targets:

• html_docs_<doc_config_file_name> - build the document (qtcreator/ qtcreator-dev) in help format, but do not generate a help file (.qch).
• html_docs_<doc_config_file_name>-online - build the document (qtcreator/qtcreator-dev) in online format.
• qch_docs_<doc_config_file_name> - build the document (qtcreator/ qtcreator-dev) in help format and generate a help file.