// 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{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:

    \list
        \li Add them to the table of contents in \c qtcreator-toc.qdoc.
        \li 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.
        \li 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.
    \endlist

    \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
    \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
    \endlist

    The Extending \QC Manual 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. The easiest way
    to do this, is to add \c {\ingroup} commands in each topic.

    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.

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

    For example:

    \badcode
    \l {Integrating Topics to Documentation}
    \endcode

    \badcode
    \sa {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.

    \section1 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 file: \c {\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 \c navigation.toctitles option in the
    document configuration file: \c {\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 (\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}}).

    \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 in \l{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 in \l{QUIP 21 | Using images in Qt documentation}.

    The following sections contain some \QC specific guidelines and examples.

    \section2 Icons

    The \l{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: \c {qtcreator/doc/qtcreator/images/icons}.

    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 folder or its 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 the
    \c {qtcreator-extraimages.qdocconf} file in the
    \c {\qtcreator\doc\qtcreator\images\extraimages} folder.

    \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 {\QC: 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{\QC Documentation}{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 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.10.0\msvc2022_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 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.10.0\msvc2022_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/qtcreator-online
        \li \c doc/html/qtcreator-dev-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{\QC: 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) 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) in online format.

        \li \c qch_docs_<doc_config_file_name> - build the document (qtcreator/
            qtcreator-dev) in help format and generate a
            help file.
    \endlist
*/
