Doc: Update guidelines for writing Qt Creator documentation

- Include information about writing Qt Design Studio Manual
  from its README file
- Update information about building the docs

Change-Id: Iaaff47ca3f07c859aa726e7e7f571042a8aadd48
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

3 files changed, 283 insertions, 225 deletions

diff --git a/doc/README.md b/doc/README.md
index 49f54c2a27..f3ddd4fe4f 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -14,6 +14,9 @@ the doc folder:
 - qtcreatordev
 - qtdesignstudio
 
+For more information, see:
+[Writing Documentation](https://doc.qt.io/qtcreator-extending/qtcreator-documentation.html)
+
 The Qt Design Studio Manual is based on the Qt Creator Manual, with
 additional topics. For more information, see the `README` file in the
 qtdesignstudio subfolder.
@@ -21,16 +24,20 @@ qtdesignstudio subfolder.
 The Extending Qt Creator Manual has its own sources. In addition, it
 pulls in API reference documentation from the Qt Creator source files.
 
-# QDoc Warnings
+# QDoc
 
 All the documents are built when you enter `make docs` on Linux or
-macOS or `nmake docs` on Windows. At the time of this writing, this
-leads to QDoc warnings being generated, because the Qt Creator Manual
-requires QDoc from Qt 5.14 or later (it links to new modules), whereas
-the Extending Qt Creator Manual requires QDoc from Qt 5.10 or earlier,
-because the doc configuration is not supported when using the Clang
-parser.
-
-To hide the doc errors and make doc builds faster, enter an option
-to write the doc errors to the log. For example, on Windows enter
-`nmake docs 2> log.txt`.
+macOS or `nmake docs` on Windows.
+
+Since Qt Creator 4.12, you need to use QDoc Qt 5.14 or later to build
+the docs. While building with QDoc from Qt 5.11 or later technically
+works, the Qt Creator Manual and Qt Design Studio Manual link to newer
+Qt modules, which means link errors will be printed.
+
+Please make the docs before submitting code changes to make sure that
+you do not introduce new QDoc warnings.
+
+While working on changes that introduce lots of warnings about missing API
+documentation, for example, you can enter an option to write the doc
+errors to the log. This helps make doc builds faster until you have
+fixed the errors. For example, on Windows enter `nmake docs 2> log.txt`.
diff --git a/doc/qtcreatordev/src/qtcreator-documentation.qdoc b/doc/qtcreatordev/src/qtcreator-documentation.qdoc
index 1d54a86912..1ebe44adfa 100644
--- a/doc/qtcreatordev/src/qtcreator-documentation.qdoc
+++ b/doc/qtcreatordev/src/qtcreator-documentation.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -61,40 +61,59 @@
         \li  API documentation, which is generated from code comments
     \endlist
 
-    \section1 Configuring the Documentation Project
+    \section1 Configuring Documentation Projects
 
     \QC documentation is written by using QDoc. For more information about using
     QDoc, see the \l{http://doc.qt.io/qt-5/qdoc-index.html}{QDoc Manual}.
 
     QDoc finds the new topics automatically, when you place them as \c {.qdoc}
-    files in the correct folder. However, to make the topics accessible to
-    readers, you must also add them to the table of contents
-    (\c {doc\src\qtcreator-toc.qdoc}) and fix the next page and previous page
-    links to them from other topics.
+    files in a doc source folder. However, to make the topics accessible to
+    readers, you must also add them to the table of contents and fix the next
+    page and previous page links to them from other topics.
 
-    \section2 Creating Folders and Files
+    \section1 Creating Folders and Files
 
-    These instructions apply only to the \QC Manual. Add API documentation
-    directly to the code source files. However, you can write an API overview
-    also as a separate \c {.qdoc} file.
+    The \c qtcreator repository contains the sources for building the following
+    documents:
 
-    Create a subfolder for your documentation in the \QC project folder in the
-    \c {doc\src} folder. Create a separate file for each topic.
+    \list
+        \li \QC Manual
+        \li Extending \QC Manual
+        \li \QDS Manual
+    \endlist
+
+    The sources for each project are stored 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 \QDS Manual is based on the \QC Manual, with additional topics.
+
+    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.
 
     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,
     links to next and previous topics, and topic title.
 
-    \section2 Integrating Topics to Documentation
+    \section1 Integrating Topics to Documentation
 
-    You must integrate your new topics to the \QC Manual and Extending \QC
-    Manual by adding links to them to the table of contents and to other
-    relevant topics.
+    You must integrate your new topics to the manuals by adding links to them
+    to the table of contents and to other relevant topics.
 
     To link to the topic, you can use the topic title. For example:
 
-    \code
+    \badcode
     \l{Integrating Topics to Documentation}
     \endcode
 
@@ -102,32 +121,148 @@
     title, the link breaks. You can avoid this risk by adding the \c {\target}
     command to your topic and then linking to the target.
 
-    \section2 Updating Next and Previous Links
+    \section2 Showing and Hiding Information
 
-    When you add new topics to a document, you must also change the navigation
-    links of the topics around them. This is very error prone when done
-    manually, and therefore we have a script called \c {fixnavi.pl} for it. For
-    the script to work, you must add the \c {\nextpage} and \c {\previouspage}
-    commands to the topic, with dummy values (for example,
-    \c {\nextpage=anything.html}).
+    \QDS uses only a subset of \QC plugins and it has its own special plugins.
+    This means that their manuals have somewhat different structures. Which, in
+    turn breaks the navigation links to previous and next pages.
 
-    \note The script creates the links according to the TOC in the topic set as
-    the value of the \c indexTitle configuration parameter
-    (\c {doc\src\qtcreator-toc.qdoc}). If your topics are not listed in the TOC,
-    the script removes the \c {\nextpage} and \c {\previouspage} commands from
-    them.
+    This also means that some of the \QC Manual source files are not needed at
+    all and some contain information that does not apply to the \QDS Manual. If
+    QDoc parsed all the \QC Manual sources, 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.
 
-    To run the script, you must have Perl installed. If you build Qt yourself,
-    you should already have it. Otherwise, download and install
-    \l{http://www.perl.org/}{Perl}.
+    \section3 Excluding Souce Files from \QDS Manual Builds
 
-    To run the script, enter the following command in the doc folder:
+    The directories to exclude from \QDS Manual builds are
+    listed as values of the \c excludedirs option in
+    \c {\doc\qtdesignstudio\config\qtdesignstudio.qdocconf}.
 
-    \list
-        \li  nmake fixnavi (on Windows)
+    You only need to edit the values of the option if you want to show or hide
+    all the contents of a directory. For example, if you add support for a \QC
+    plugin that was previously not supported by \QDS, you should remove the
+    directory that contains the documentation for the plugin from the values.
 
-        \li  make fixnavi (on Linux)
-    \endlist
+    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 directories.
+
+    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 directory.
+
+    If a directory 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
+    subdirectory called \c {creator-only}, which is excluded from the \QDS
+    Manual builds.
+
+    \section3 Hiding Text in \QC Manual Sources
+
+    The \c qtcreator define is specified as a value of the
+    \c defines option in the \QC QDoc configuration file,
+    \c {\doc\qtcreator\config\qtcreator-project.qdocconf}.
+    It is mostly used in the \QC Manual sources to hide \QC
+    specific information when the \QDS Manual is built.
+
+    The \c {\else} command is sometimes used to replace some \QC specific text
+    with text that applies to \QDS. For example, the following \c if-else
+    statement is needed in the \QC Manual sources, because the project wizards
+    in \QDS are different from those in \QC, and are therefore described in
+    a new topic that is located in the \QDS Manual sources:
+
+    \badcode
+    For more information, see
+    \if defined(qtcreator)
+    \l{Creating Qt Quick Projects}.
+    \else
+    \l{Creating UI Prototype Projects}.
+    \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} directory. Some
+    files are used to include subsections in topics in the \QC Manual sources.
+
+    Screenshots and other illustrations are stored in the
+    \c {\qtdesignstudio\images} directory.
+
+    If you add new topics to the \QDS Manual, add links to them to the table
+    of contents in \c {qtdesignstudio-toc.qdoc} and check the values of the
+    navigation links around them.
+
+    \section3 Including Sections in \QC Manual Sources
+
+    \QMLD is an integral part of both \QC and \QDS. Therefore, most topics that
+    describe it are needed in the manuals of both tools. You can use the
+    \c {\include} command in the \QC Manual sources to include \c {.qdocinc}
+    files from the \QDS Manual sources when building the \QDS Manual.
+
+    For example, the following lines in the
+    \c {\doc\qtcreator\src\qtquick\qtquick-components.qdoc}
+    file add information about creating and using \QDS Components
+    to the \e {Creating Components} topic that is pulled from the
+    \QC Manual sources:
+
+    \badcode
+    \if defined(qtdesignstudio)
+    \include qtdesignstudio-components.qdocinc creating studio components
+    \include qtdesignstudio-components.qdocinc studio components
+    \endif
+    \endcode
+
+    Similarly, you can use include files to include subsections in different
+    main level topics in the two manuals.
+
+    \section2 Updating Next and Previous Links
+
+    When you add new topics to a document, you must also change the navigation
+    links of the topics around them.
+
+    The navigation order of the topics in the \QC Manual is specified in
+    \c {\doc\qtcreator\src\qtcreator-toc.qdoc} and that of the topics in the
+    \QDS Manual in \c {\doc\qtdesignstudio\src\qtdesignstudio-toc.qdoc}. If
+    you add topics to or move them around in a TOC file, you must adjust the
+    navigation links accordingly.
+
+    The \c qtdesignstudio define is specified as a value of
+    the \c defines option in the \QDS Manual configuration file,
+    \c {qtcreator\doc\qtdesignstudio\config\qtdesignstudio.qdocconf}.
+    It is mostly used in the \QC Manual sources to specify values for the
+    \c {\previouspage} and \c {\nextpage} commands depending on whether
+    the \QDS Manual or \QC Manual is being built. For example, the
+    following \c if-else statement is needed, because only the Git
+    version control system is integrated to \QDS, and information about
+    the other systems integrated to \QC is hidden:
+
+    \badcode
+    \page creator-vcs-git.html
+    \if defined(qtdesignstudio)
+    \previouspage studio-projects.html
+    \nextpage studio-importing-designs.html
+    \else
+    \previouspage creator-vcs-cvs.html
+    \nextpage creator-vcs-mercurial.html
+    \endif
+    \endcode
 
     \section1 Writing Text
 
@@ -153,7 +288,7 @@
     Use the \c {\image} and \c {\inlineimage} QDoc commands to refer to images
     from the text. You do not need to add paths to image names. For example:
 
-    \code
+    \badcode
     \image riot.png
     \endcode
 
@@ -182,7 +317,7 @@
             image also in the screen capture tool).
 
         \li To highlight parts of the screen shot, use the images of numbers
-            that are stored in \c{doc\images\numbers} in the \QC repository.
+            that are stored in \c{doc/images/numbers} in the \QC repository.
 
         \li Before you submit the images to the repository, optimize them to
             save space.
@@ -201,9 +336,9 @@
     you can just insert the number of the element you are referring to in
     brackets.
 
-    You can find a set of images that show the numbers from 1 to 10  in the
-    \c doc\images\numbers directory (or in the \c qtdoc module sources in
-    \c doc\images\numbers).
+    You can find a set of images that show the numbers from 1 to 10 in the
+    \c doc/images/numbers directory (or in the \c qtdoc module sources in
+    \c doc/images/numbers).
 
     To use the numbers, copy-paste the number images on the screenshot to the
     places that you want to refer to from text.
@@ -211,7 +346,7 @@
     \section2 Optimizing Images
 
     Save images in the PNG format in the \QC project folder in the
-    \c {doc\images} folder. Binary images can easily add megabytes to the Git
+    \c {doc/images} folder. 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 size below 50 kilobytes. To achieve this
     goal, crop images so that only relevant information is visible in them.
@@ -262,31 +397,38 @@
     folder (or any folder that contains your project). To optimize a screenshot,
     enter the following command (here, from the \QC project folder):
 
-    \code
+    \badcode
     optipng -o 7 -strip all doc/images/<screenshot_name>
     \endcode
 
     \section1 Building Documentation
 
-    You use QDoc to build the documentation. Build the documentation from time
-    to time, to check its structure and the validity of the QDoc commands.
-    The error messages that QDoc issues are generally very useful for
-    troubleshooting.
+    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 run \c qmake from an installed Qt to build documentation.
 
-    For more information about setting up the build environment if you do not
-    want to build the whole Qt, see
+    \note Since \QC version 4.12, only Qt 5.14.0 or later is supported
+    for building documentation.
+
+    For more information about setting up the build environment with a
+    self-built Qt if you do not want to build the whole Qt, see
     \l{https://wiki.qt.io/Building_Qt_Documentation}{Building Qt Documentation}
     on the Qt wiki.
 
     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. Since \QC
-    version 3.3, only Qt 5 is supported for building documentation. 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:
+    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)}
@@ -299,45 +441,82 @@
     running it on a web server.
 
     \note If the styles look wrong to you when reading help files in \QC or \QA,
-    you might be looking at them in the QTextBrowser instead of the Qr WebEngine
+    you might be looking at them in the QTextBrowser instead of the Qt WebEngine
     browser. This happens if you do not have Qt WebEngine installed.
 
+    \section2 Documentation Build Commands
+
     To build documentation for the sources from the qtcreator master branch, use
-    build scripts defined in the doc.pri file. To build all \QC docs in the
-    help format and to create help files (.qch), enter the following build
+    build scripts defined in the doc.pri file. To build the docs in the
+    HTML format and to create help files (.qch), enter the following build
     commands from the project folder (after running qmake):
 
     \list
-        \li  nmake docs (on Windows)
+        \li \c {nmake docs} (on Windows)
 
-        \li  make docs (on Linux and \macos)
+        \li \c {make docs} (on Linux and \macos)
     \endlist
 
-    The \QC Manual HTML files are generated in the \c {doc/qtcreator} directory.
-    The Extending \QC Manual files are generated in the
-    \c {doc/qtcreator-dev} directory. The help files (\c {.qch}) are generated in the
+    The HTML documentation is generated in the following folders:
+
+    \list
+        \li \c doc/html/qtcreator
+        \li \c doc/html/qtcreatordev
+        \li \c doc/html/qtdesignstudio
+    \endlist
+
+    The help files (\c {.qch}) are generated in the
     \c {share/doc/qtcreator} directory in the \QC build directory on Windows and
     Linux, and in the \c {bin/Qt Creator.app/Contents/Resources/app} directory
-    on \macos. You can view the HTML files in a browser and the help files in
+    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{http://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation}
     {Adding External Documentation}.
 
-    Besides \c docs, you have the following options:
+    Besides \c docs, you have the following options for building a particular
+    document in a particular format:
 
     \list
-        \li html_docs_qtcreator - build \QC Manual in help format, but do not
+        \li \c html_docs_qtcreator - build \QC Manual in help format, but do not
             generate a help file
 
-        \li html_docs_qtcreator-dev - build Extending \QC Manual in help
+        \li \c html_docs_qtcreator-dev - build Extending \QC Manual in help
             format, but do not generate a help file
 
-        \li qch_docs_qtcreator - build \QC Manual in help format and generate
+        \li \c qch_docs_qtcreator - build \QC Manual in help format and generate
             a help file (.qch)
 
-        \li qch_docs_qtcreator-dev - build Extending \QC Manual in help format
+        \li \c qch_docs_qtcreator-dev - build Extending \QC Manual in help format
             and generate a help file (.qch)
     \endlist
 
+    \section3 Building the \QDS Manual
+
+    To get the correct product name and version, you must run \c {qmake -r} on
+    \c {qtcreator.pro} with the \c IDE_BRANDING_PRI option set to the absolute
+    path of \c {ide_branding.pri} in the \QDS (private) repository.
+
+    For example, on Windows enter (all on one line):
+
+    \badcode
+    C:\dev\qtc-super\qtcreator>..\..\..\Qt\5.14.1\msvc2017_64\bin\qmake.exe
+        qtcreator.pro -r
+        IDE_BRANDING_PRI=C:\dev\tqtc-plugin-qtquickdesigner\studiodata\branding\ide_branding.pri
+    \endcode
+
+    To build the \QDS Manual:
+
+    \list 1
+        \li Run \c qmake from Qt 5.14.0, or later with the path to the branding
+            information as an option (all on one line):
+
+            \c {<relative_path_to>/qmake.exe
+            qtcreator.pro -r
+            IDE_BRANDING_PRI=<absolute_path_to>ide_branding.pri}
+        \li Run \c {make docs} on Linux and macOS or \c {nmake docs}
+            on Windows.
+    \endlist
 */
diff --git a/doc/qtdesignstudio/README.md b/doc/qtdesignstudio/README.md
index 74a5f5c741..c23a21a9a2 100644
--- a/doc/qtdesignstudio/README.md
+++ b/doc/qtdesignstudio/README.md
@@ -6,151 +6,23 @@ Manual are pulled in from Qt Creator sources. This is enabled by creating
 separate table of contents files for each Manual and by using defines
 to hide and show information depending on which Manual is being built.
 
-This readme file describes how to build the Qt Design Studio Manual and how to
-edit or add source files when necessary.
+Because branding information is needed to use the correct product name and
+version, you must run `qmake -r` on `qtcreator.pro` with the `IDE_BRANDING_PRI`
+option set to the absolute path of `ide_branding.pri` in the Qt Design Studio
+repository.
 
-## Building the Qt Design Studio Manual
-
-1. Edit qtcreator\qtcreator.pri as follows:
-   `isEmpty(IDE_DISPLAY_NAME):  IDE_DISPLAY_NAME = Qt Design Studio`
-   `isEmpty(IDE_ID):            IDE_ID = qtdesignstudio`
-   `isEmpty(IDE_CASED_ID):      IDE_CASED_ID = QtDesignStudio`
-2. Switch to the `qtcreator\doc\qtdesignstudio` directory.
-4. Run `qmake` from Qt 5.14.0, or later
-  (because you need the Qt Timeline and Qt Quick 3D module docs)
-5. Run `make docs` on Linux and macOS or `nmake docs` on Windows.
-
-The docs are generated in `qtcreator\doc\qtdesignstudio\doc\qtdesignstudio`
-
-## Showing and Hiding Information
-
-Qt Design Studio uses only a subset of Qt Creator plugins and it has its
-own special plugins. This means that their manuals have somewhat different
-structures. Which, in turn breaks the navigation links to previous and next
-pages.
-
-This also means that some of the Qt Creator doc source files are not needed at
-all and some contain information that does not apply to the Qt Design Studio
-Manual. If QDoc parses all the Qt Creator doc sources, it would generate
-HTML files for each topic and include those files and all the images that they
-refer to in the help compilation files. This would unnecessarily increase the
-size of the help database and pollute the help index with references to files
-that are not actually listed in the table of contents of the manual. To avoid
-this, the files that are not needed are excluded from doc builds in the doc
-build configuration file.
-
-### Fixing the Navigation Links
-
-The navigation order of the topics in the Qt Design Studio Manual is specified
-in `qtcreator\doc\qtdesignstudio\src\qtdesignstudio-toc.qdoc`. The
-order of the topics in the Qt Creator Manual is specified in
-`qtcreator\doc\src\qtcreator-toc.qdoc`. If you add topics to or move them
-around in the TOC file, you must adjust the navigation links accordingly.
-
-The `qtdesignstudio` define is specified as a value of the `defines` option in
-the Qt Design Studio doc configuration file,
-`qtcreator\doc\qtdesignstudio\config\qtdesignstudio.qdocconf`. It is
-mostly used in the Qt Creator doc sources to specify values for the
-\previouspage and \nextpage commands depending on whether the Qt Design Studio
-Manual or Qt Creator Manual is being built. For example, the following if-else
-statement is needed, because the `quick-buttons.html` is excluded from the
-Qt Design Studio Manual:
-
-`\page quick-components.html`
-`\previouspage creator-using-qt-quick-designer.html`
-`\if defined(qtdesignstudio)`
-`\nextpage qtquick-navigator.html`
-`\else`
-`\nextpage quick-buttons.html`
-`\endif`
-
-### Excluding Souce Files from Builds
-
-The directories to exclude from Qt Design Studio Manual builds are listed as
-values of the `excludedirs` option in `\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 directory. For example, if you add support for a Qt Creator
-plugin that was previously not supported by Qt Design Studio, you should remove
-the directory that contains the documentation for the plugin from the values.
-
-To hide or show individual topics within individual `.qdoc` files, you need to
-move the files in the Qt Creator doc source (`qtcreator\doc\src`) to or from
-excluded directories.
-
-For example, if support for iOS were added, you would need to check whether the
-information about iOS support is applicable to Qt Design Studio Manual. If yes,
-you would need to remove the following line from the `excludedirs` value:
+For example, on Windows enter (all on one line):
 
-`../../src/ios \`
+`C:\dev\qtc-super\qtcreator>..\..\..\Qt\5.14.1\msvc2017_64\bin\qmake.exe
+    qtcreator.pro -r
+    IDE_BRANDING_PRI=C:\dev\tqtc-plugin-qtquickdesigner\studiodata\branding\ide_branding.pri`
 
-You would then use defines to hide any Qt Creator specific information from the
-source file in the directory.
-
-If a directory contains some files that are needed in both manuals and some that
-are only needed in the Qt Creator Manual, the latter are located in a
-subdirectory called `creator-only`, which is excluded from the Qt Design Studio
-doc builds.
-
-### Hiding Text in Qt Creator Doc Sources
-
-The `qtcreator` define is specified as a value of the `defines` option in the
-Qt Creator doc configuration file,
-`qtcreator\doc\src\config\qtcreator-project.qdocconf`. It is mostly used in the
-Qt Creator doc sources to hide Qt Creator specific information when the Qt
-Design Studio Manual is built.
-
-The `\else` command is sometimes used to replace some Qt Creator specific text
-with text that applies to Qt Design Studio. For example, the following if-else
-statement is needed in the Qt Creator doc sources, because the project wizards
-in Qt Design Studio are different from those in Qt Creator, and are therefore
-described in a new topic that is located in the Qt Design Studio doc sources:
-
-`For more information, see`
-`\if defined(qtcreator)`
-`\l{Creating Qt Quick Projects}.`
-`\else`
-`\l{Creating UI Prototype Projects}.`
-`\endif`
-
-Note that titles in the two manuals can be identical only if the page is
-excluded from the Qt Design Studio 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 `.index` file.
-
-## Writing About Qt Design Studio Specific Features
-
-Qt Design Studio specific plugins and features are described in a set of doc
-source files located in the `qtcreator\doc\qtdesignstudio\src` directory. Some
-files are used to include subsections in topics in the Qt Creator doc sources.
-
-Screenshots and other illustrations are stored in the `\qtdesignstudio\images`
-directory.
-
-### Adding Topics
-
-If you add new topics to the Qt Design Studio Manual, add links to them to the
-table of contents in `qtdesignstudio-toc.qdoc` and check the values of the
-navigation links around them.
-
-### Including Sections in Qt Creator Doc Sources
-
-Qt Quick Designer is an integral part of both Qt Creator and Qt Design Studio.
-Therefore, most topics that describe it are needed in the manuals of both tools.
-You can use the `\include` command in the Qt Creator doc sources to include
-`.qdocinc` files from the Qt Design Studio doc sources when building the
-Qt Design Studio Manual.
-
-For example, the following lines in the
-`qtcreator\doc\src\qtquick\qtquick-components.qdoc` file add information about
-creating and using Qt Design Studio Components to the `Creating Components`
-topic that is pulled from the Qt Creator doc sources:
+## Building the Qt Design Studio Manual
 
-`\if defined(qtdesignstudio)`
-`\include qtdesignstudio-components.qdocinc creating studio components`
-`\include qtdesignstudio-components.qdocinc studio components`
-`\endif`
+1. Run `qmake` from Qt 5.14.0, or later with the path to the branding
+   information as a parameter:
+   `<relative_path_to>\qmake.exe qtcreator.pro -r IDE_BRANDING_PRI=<absolute_path_to>\tqtc-plugin-qtquickdesigner\studiodata\branding\ide_branding.pri`
+5. Run `make docs` on Linux and macOS or `nmake docs` on Windows.
 
-Similarly, you can use include files to include subsections in different main
-level topics in the two manuals.
+The docs are generated in `qtcreator\doc\html\qtdesignstudio` with the
+Qt Design Studio branding.