feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity
Files
d30dda07a12c458cf2dd86fe02c9b0293bcd4bdf
qt-creator/doc/qtcreatordev/src/qtcreator-documentation.qdoc
Eike Ziller 8500dd03bf Merge remote-tracking branch 'origin/13.0' 
Conflicts:
	doc/qtcreator/src/overview/creator-only/creator-keyboard-shortcuts.qdoc

Change-Id: I2db85da9f4a0593217951313020d71d430986961
2024-03-22 15:13:34 +01:00

508 lines
21 KiB
Plaintext
Raw Blame History

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\previouspage external-tool-spec.html
\page qtcreator-documentation.html
\nextpage coding-style.html
\title Writing Documentation
When you add plugins or contribute new features to \QC, 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 \QC documentation.
When you contribute a plugin, you should write documentation both for the
developers who use \QC and for those who develop it.
Add the following types of topics to the \QC Manual or as a separate plugin
manual if your plugin is located in a repository of its own:
\list
\li Overview topics, which describe the purpose of your plugin from the
viewpoint of \QC users.
\li Tutorials, which describe how to create different types of
Qt applications.
\li How-to topics, which describe how to perform tasks with your plugin
as part of \QC.
\li Reference topics, which contain information that developers
occasionally need to look up.
\endlist
Add the following types of topics to the Extending \QC Manual:
\list
\li Overview topic, which describes the architecture and use cases for
your plugin from the viewpoint of \QC developers.
\li API documentation, which is generated from code comments.
\endlist
\section1 Configuring Documentation Projects
Use QDoc to write \QC documentation. For more information about using
QDoc, see the \l{https://doc.qt.io/qt/qdoc-index.html}{QDoc Manual}.
QDoc finds the new topics automatically, when you place them as \c {.qdoc}
files in a doc source folder. However, to make the topics accessible to
readers, you must also add them to the table of contents, use the
\l{https://doc.qt.io/qt-6/19-qdoc-commands-grouping.html#ingroup-command}
{\c {\ingroup}} command to automatically add them to lists of topics, or
use the \l{https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html#l-command}
{\c {\l (link)}} and
\l{https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html#sa-see-also}
{\c {\sa (see also)}} commands to add links to them from other topics.
\section1 Creating Folders and Files
The \c qtcreator repository contains the sources for building the following
documents:
\list
\li \QC Manual
\li Extending \QC Manual
\li \QDS Manual
\endlist
The sources for each project are in the following subfolders of
the \QC project folder:
\list
\li \c \doc\qtcreator\src
\li \c \doc\qtcreatordev\src
\li \c \doc\qtdesignstudio\src
\endlist
The \QC Manual and the \QDS Manual share some topics about developing
Qt Quick applications, writing and debugging code, previewing QML files,
and so on.
The Extending \QC Manual has its own sources. In addition, it
pulls in API reference documentation from the \QC source files. Add
code documentation directly to the code source files. However, you can
write an API overview also as a separate \c {.qdoc} file.
Create a subfolder for your documentation in the appropriate \c src folder.
Create a separate file for each topic.
\image qtcreator-doc-folder.webp {doc folder in file manager}
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
\l{https://doc.qt.io/qt-6/13-qdoc-commands-topics.html#page-command}
{\c {\page}}), navigation links, grouping, and topic title.
\section1 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. In addition, use
the \l {https://doc.qt.io/qt-6/15-qdoc-commands-navigation.html#previouspage-command}
{\c {\previouspage}} and
\l {https://doc.qt.io/qt-6/15-qdoc-commands-navigation.html#nextpage-command}
{\c {\nextpage}} commands to add navigation links between topics.
To link to the topic, you can use the topic title. For example:
\badcode
\l {Integrating Topics to Documentation}
\endcode
\badcode
\sa {Integrating Topics to Documentation}
\endcode
\badcode
\previouspage {Integrating Topics to Documentation}
\endcode
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
\l{https://doc.qt.io/qt-6/08-qdoc-commands-creatinglinks.html#target-command}
{\c {\target}} command to your topic and then linking to the target.
\section2 Showing and Hiding Information
\QDS uses only a subset of \QC plugins and it has its own special plugins.
Their manuals have different structure and content, so only some
source files are needed in both manuals. All files from
\c \doc\qtdesignstudio\ are excluded from the \QC Manual builds.
If QDoc parsed all the \QC Manual sources when you build the \QDS Manual, it
would generate HTML files for each
topic and include those files and all the images that they refer to in the
\QDS help compilation files. This would unnecessarily increase the size of
the \QDS help database and pollute the help index with references to files
that are not actually listed in the table of contents of the \QDS Manual.
To avoid this, some files are excluded from the \QDS Manual builds.
\section3 Excluding Source Files from \QDS Manual Builds
The folders to exclude from \QDS Manual builds are
listed as values of the \c excludedirs option in
\c {\doc\qtdesignstudio\config\qtdesignstudio.qdocconf}.
You only need to edit the values of the option if you want to show or hide
all the contents of a folder. For example, if you add support for a \QC
plugin that was previously not supported by \QDS, you should remove the
folder that contains the documentation for the plugin from the values.
To hide or show individual topics within individual \c {.qdoc} files, you
need to move the files in the \QC Manual source (\c \doc\qtcreator\src) to
or from the excluded folders.
For example, if support for iOS were added, you would need to check whether
the information about iOS support is applicable to \QDS Manual. If yes,
you would need to remove the following line from the \c excludedirs value:
\badcode
../../src/ios \
\endcode
You would then use defines to hide any \QC specific information from the
source file in the folder.
If a folder contains some files that are needed in both manuals and some
that are only needed in the \QC Manual, the latter are located in a
subfolder called \c {creator-only}, which is excluded from the \QDS
Manual builds.
If you add a new folder in \c \doc\qtcreator\src that you don't need in the
\QDS Manual, add the folder path and name as a value of \c excludedirs.
\section3 Hiding Text from HTML Files
The \c qtcreator define is specified as a value of the
\l{ https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#defines}
{\c defines} variable in the \QC QDoc configuration file,
\c {\doc\qtcreator\config\qtcreator-project.qdocconf}.
Use it as a value of the
\l{https://doc.qt.io/qt-6/12-0-qdoc-commands-miscellaneous.html#if-command}
{\c {\if}} command in the \QC Manual sources to hide \QC specific information
from the generated HTML files when you build the \QDS Manual.
The \c qtdesignstudio define is specified as a value of the \c defines
variable in the \QDS Manual configuration file,
\c {qtcreator\doc\qtdesignstudio\config\qtdesignstudio.qdocconf}.
Use it with the \c {\if} command in the \QC Manual sources to hide \QDS
specific information from the generated HTML when you build the \QC Manual.
You can use the
\l{https://doc.qt.io/qt-6/12-0-qdoc-commands-miscellaneous.html#else-command}
{\c {\else}} command to display different text depending on which manual is built.
End the conditional text with the
\l{https://doc.qt.io/qt-6/12-0-qdoc-commands-miscellaneous.html#endif-command}
{\c {\endif}} command.
For example, the terminology around the code editor is different in \QC and
\QDS, so different text is shown depending on which manual is built:
\badcode
\li \l{Writing Code}
\if defined(qtdesignstudio)
The \l{Code} view offers services, such as semantic highlighting,
syntax checking, code completion, code indentation, and in-line
error indicators while you are typing.
\else
Writing, editing, and navigating in source code are core tasks in
application development. Therefore, the code editor is one of the
key components of \QC. You can use the code editor in the
\uicontrol Edit mode.
\endif
\endcode
\note Section titles in the two manuals can be identical only if the page is
excluded from the \QDS Manual. In this case, QDoc can correctly determine
the link target. If you add a link to a section title that appears twice in
the doc source files, QDoc uses the first reference to that title in the
\c {.index} file.
\section3 Writing About \QDS Specific Features
\QDS specific plugins and features are described in a set of doc
source files located in the \c {\doc\qtdesignstudio\src} folder.
Save screenshots and other illustrations in \c {\qtdesignstudio\images}.
If you add new topics to the \QDS Manual, add links to them to the table
of contents in \c {qtdesignstudio-toc.qdoc}.
\section2 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 \e {All Topics}, which
is in the following files:
\list
\li \QC: \c {\qtcreator\doc\qtcreator\src\qtcreator-toc.qdoc}
\li \QDS: \c {\qtcreator\doc\qtdesignstudio\src\qtdesignstudio-toc.qdoc}
\endlist
The title of the topic to use for automatically generating the navigation
links is set as the value of the \c navigation.toctitles option in the
document configuration file:
\list
\li \QC: \c {\doc\qtcreator\config\qtcreator-project.qdocconf}
\li \QDS: \c {\doc\qtdesignstudio\config\qtdesignstudio.qdocconf}
\endlist
When you add new topics, you must add them either to the TOC or to a
group of topics (\c {\ingroup}) that is used to generate a list in the TOC
(\l{https://doc.qt.io/qt-6/12-0-qdoc-commands-miscellaneous.html#generatelist-command}
{\c {\generatelist}}).
In the \QC Manual, you can see the current groups in the \e {How To} and
\e {Reference} sections of the TOC. You can add new groups.
\note You do not need to manually change the navigation links, but they must
be there with some initial values for QDoc to replace with the values from
the TOC when you build the docs.
\section1 Adding Documentation for Independent Plugins
You can develop \QC 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 \QC plugin manuals:
\e {\QC <Plugin Name> Plugin Manual}.
\section1 Writing Text
Follow the guidelines for
\l{http://wiki.qt.io/Writing_Qt_Documentation}{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.
\section2 Capitalizing Headings
Use the book title capitalization style for all titles and section headings
(\l{https://doc.qt.io/qt-6/20-qdoc-commands-namingthings.html#title-command}
{\c {\title}},
\l {https://doc.qt.io/qt-6/05-qdoc-commands-documentstructure.html#sectionone-command}
{\c {\section1}}, \c {\section2}, and so on). For more
information, see \l{Using Book Style Capitalization}.
\section1 Using Images
You can illustrate documentation by using screen shots, diagrams, and
animated images, for example.
Follow the guidelines set in \l{https://contribute.qt-project.org/quips/21}
{QUIP 21 | Using images in Qt documentation}.
The following sections contain some \QC and \QDS specific guidelines and
examples.
\section2 Icons
The \l{https://doc.qt.io/}{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 locations, depending on whether they are used in both manuals
or just the \QDS Manual:
\list
\li \c qtcreator/doc/qtcreator/images/icons - used in the \QC Manual.
\li \c qtcreator/doc/qtdesignstudio/images/icons - used only in the
\QDS Manual.
\endlist
You can use a script located in \c qttools/util/recolordocsicons/ to recolor
icons.
\section2 Saving Images
Save images in PNG or WebP format in the \QC project folder in the
\c doc/qtcreator/images or \c doc/qtdesignstudio/images folder or their
subfolders.
Before committing PNG images, optimize them by using an image optimization
tool, such as OptiPNG. To invoke it from the \QC project enter the following
command:
\badcode
optipng -o 7 -strip all doc/images/<screenshot_name>
\endcode
\section2 Linking to Youtube Videos
You can use the \c {\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
\c {qtcreator\doc\config\macros.qdocconf} and
\c {qtcreator\doc\config\macros-online.qdocconf} files. To
use the macro, you need to save a thumbnail of the video in
\c {qtcreator\doc\qtcreator\images\extraimages\images}.
You must add the filename of the thumbnail file to
\c {qtcreator-extraimages.qdocconf} and \c {qtdesignstudio-extraimages.qdocconf}
files in the \c {\qtcreator\doc\qtcreator\images\extraimages} folder.
If you'll only link to the video from the \QC Manual or the \QDS Manual,
you'll only need to add the thumbnail filename to the \c extraimages.qdocconf
file for that project.
\section1 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.
\section2 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 \QC versions.
The templates to use are defined by the
\c {qt5/qtbase/doc/global/qt-html-templates-offline.qdocconf}
and \c {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:
\list
\li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)}
for help files.
\li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)}
for publishing on the web.
\endlist
\note If the styles look wrong to you when reading help files in \QC or \QA,
you might be using the QTextBrowser as the help engine backend instead of
litehtml. For more information, see
\l {https://doc.qt.io/qtcreator/creator-how-to-get-help.html#select-help-viewer-backend}
{Select help viewer backend}.
To build documentation for the sources from the \c 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 \l{https://doc.qt.io/qtcreator/index.html}{doc.qt.io}.
\section3 Using CMake
When using CMake, the docs are built in the \QC \e {build folder} or a
separate doc build folder, not in the project folder.
To get the correct product name and version when building \QDS Manual, you
must run CMake with the BUILD_DESIGNSTUDIO option.
To build docs with CMake in a separate doc build folder:
\list 1
\li Create a folder for the built docs and switch to it. For example,
\c {C:\dev\qtc-doc-build}.
\li In the doc build folder, enter the following command:
\badcode
cmake -DWITH_DOCS=ON "-DCMAKE_PREFIX_PATH=<path_to_qt>" <path_to_qtcreator_src>
\endcode
For example (all on one line):
\badcode
C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON
"-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
C:\dev\qtc-super\qtcreator
\endcode
\li To also build Extending \QC Manual, add the following option:
\c {-DBUILD_DEVELOPER_DOCS=ON}
\li To also build the \QDS Manual, add the following option:
\c {-DBUILD_DESIGNSTUDIO=ON}
For example:
\badcode
C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON -DBUILD_DEVELOPER_DOCS=ON
-DBUILD_DESIGNSTUDIO=ON
"-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
C:\dev\qtc-super\qtcreator
\endcode
\li To build the docs using the online style, use the following option
instead of \c {-DWITH_DOCS=ON}:
\c {-DWITH_ONLINE_DOCS=ON}
For example:
\badcode
C:\dev\qtc-doc-build>cmake -DWITH_ONLINE_DOCS=ON
-DBUILD_DEVELOPER_DOCS=ON
-DBUILD_DESIGNSTUDIO=ON
"-DCMAKE_PREFIX_PATH=C:\Qt\6.4.0\msvc2019_64"
C:\dev\qtc-super\qtcreator
\endcode
\note If you already ran CMake \c {-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:
\badcode
cmake -DWITH_DOCS=OFF -DWITH_ONLINE_DOCS=ON
\endcode
\li Enter the following doc build command to build both HTML docs and
the help files (.qch):
\badcode
cmake --build . --target docs
\endcode
\li Alternatively, to build only the HTML docs, enter:
\badcode
cmake --build . --target html_docs
\endcode
\endlist
\note You can enter \c cmake-gui to open the graphical CMake configuration
tool, where you can select build options.
The HTML files for the documentation are generated in the following
folders:
\list
\li \c doc/html/qtcreator
\li \c doc/html/qtcreator-dev
\li \c doc/html/qtdesignstudio
\li \c doc/html/qtcreator-online
\li \c doc/html/qtcreator-dev-online
\li \c doc/html/qtdesignstudio-online
\endlist
The help files (\c {.qch}) are generated in the \c {share/doc/qtcreator}
folder or in the \c {<application_name>.app/Contents/Resources/doc\} folder
on \macos.
You can view the HTML files in a browser and the help files in
the \QC \uicontrol Help mode. For more information about adding
the help files to \QC, see
\l{https://doc.qt.io/qtcreator/creator-how-to-add-external-documentation.html}
{Add external documentation}.
\section2 Additional Build Commands
Besides \c docs and \c html_docs, you can use the following build targets:
\list
\li \c html_docs_<doc_config_file_name> - build the document (qtcreator/
qtcreator-dev/qtdesignstudio) in help format, but do not generate a
help file (.qch).
\li \c html_docs_<doc_config_file_name>-online - build the document
(qtcreator/qtcreator-dev/qtdesignstudio) in online format.
\li \c qch_docs_<doc_config_file_name> - build the document (qtcreator/
qtcreator-dev/qtdesignstudio) in help format and generate a
help file.
\endlist
*/
View Git Blame Copy Permalink