path: root/doc/qtcreatordev/src/qtcreator-documentation.qdoc

// 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
*/