Doc: Divide "Creating Projects" into an explanation and how-to topics

Task-number: QTCREATORBUG-29361
Change-Id: I623d824e423da950df9643c42d85b485daccfe4b
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

doc/qtcreator/src/editors/creator-locator.qdoc

@@ -104,7 +104,7 @@
     or use the handle next to the locator window to increase the window width.
 
     \if defined(qtcreator)
-    If the locator does not find some files, see \l{Specifying Project Contents}
+    If the locator does not find some files, see \l{Specify project contents}
     for how to make them known to the locator.
     \endif
 

doc/qtcreator/src/editors/creator-only/creator-beautifier.qdoc

@@ -105,7 +105,7 @@
 
                 \li Select \uicontrol {Use file *.astylerc defined in project files}
                     or \uicontrol {Use file uncrustify.cfg defined in project files},
-                    to use the configuration file \l{Specifying Project Contents}
+                    to use the configuration file \l{Specify project contents}
                     {defined in the project file} as the configuration file
                     for the selected tool.
 

doc/qtcreator/src/editors/creator-search.qdoc

@@ -122,7 +122,7 @@
 
                     \if defined(qtcreator)
                     If you cannot find some files, see
-                    \l{Specifying Project Contents} for how
+                    \l{Specify project contents} for how
                     to declare them as a part of the project.
                     \endif
 

doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc

@@ -61,7 +61,11 @@
 
     \list
         \li \l {Add a license header template for C++ code}
+        \li \l {Add subprojects to projects}
         \li \l {Develop Qt for Python applications}
+        \li \l {Specify project contents}
+        \li \l {Select the build system}
+        \li \l {Use project wizards}
     \endlist
 
     \section1 Use \QC

doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc

@@ -35,7 +35,7 @@
     \section1 Adding Missing Files
 
     The process to add files to deploy depends on the build system you use.
-    For more information, see \l{Specifying Project Contents}.
+    For more information, see \l{Specify project contents}.
 
     \section2 CMake Builds
 

doc/qtcreator/src/projects/creator-only/creator-how-to-select-build-systems.qdoc

@@ -0,0 +1,60 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \previouspage creator-project-creating.html
+    \page creator-how-to-select-build-system.html
+    \nextpage creator-file-creating.html
+
+    \ingroup creator-how-to-projects
+
+    \title Select the build system
+
+    You can use several build systems to build your projects:
+
+    \list
+        \li \l {Build with CMake}{CMake} is a cross-platform system for build
+            automation that helps simplify the build process for development
+            projects across different platforms. It automates the generation of
+            build configurations. For more information, see \l {Setting Up CMake}.
+        \li \l{qmake Manual}{qmake} is an alternative to CMake for automating the
+            generation of build configurations. Qt installers install and
+            configure qmake. To use one of the other supported build systems,
+            you need to set it up.
+        \li \l {https://mesonbuild.com/}{Meson} is a fast and user-friendly
+            open-source build system that aims to minimize the time developers spend
+            writing or debugging build definitions and waiting for the build system
+            to start compiling code. For more information, see \l {Setting Up Meson}.
+        \li \l{Qbs Manual}{Qbs} is an all-in-one build tool that generates a build graph
+            from a high-level project description (like qmake or CMake do) and executes
+            the commands in the low-level build graph (like make does). For more
+            information, see \l{Setting Up Qbs}.
+    \endlist
+
+    Typically, you select the build system when you create a project.
+
+    \section1 Migrate to another build system
+
+    To export a project to some other build system, such as Microsoft Visual
+    Studio, select \uicontrol Build > \uicontrol {Run Generator}, and select
+    a generator in the list. \QC generates the build files, such as .vcxproj,
+    in the project's build directory.
+
+    The tool that you use to build the project (qmake or CMake) provides the
+    generators. Their availability depends on the version of the build tool,
+    host platform, and properties of the host system.
+    Also, a JSON compilation database generator is available if the
+    \l{Parsing C++ Files with the Clang Code Model}{Clang Code Model plugin}
+    is enabled (default).
+
+    \section1 Set preferences for building and running
+
+    To change the location of the project directory, and to specify settings
+    for building and running projects, select \uicontrol Edit >
+    \uicontrol Preferences > \uicontrol {Build & Run} > \uicontrol General.
+
+    Specify build and run settings for different target platforms, in the
+    \uicontrol Projects mode.
+
+    \sa {Specifying Build Settings}, {Build Systems}, {Use project wizards}
+*/

doc/qtcreator/src/projects/creator-only/creator-projects-build-systems.qdocinc

@@ -1,61 +0,0 @@
-// Copyright (C) 2023 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-
-// **********************************************************************
-// NOTE: the sections are not ordered by their logical order to avoid
-// reshuffling the file each time the index order changes (i.e., often).
-// Run the fixnavi.pl script to adjust the links to the index order.
-// **********************************************************************
-
-/*!
-//! [build systems]
-
-    \section1 Selecting the Build System
-
-    You can use several build systems to build your projects:
-
-    \list
-
-    \li \l{qmake Manual}{qmake} is a cross-platform system for build automation
-    that helps simplify the build process for development projects across
-    different platforms. qmake automates the generation of build configurations
-    so that you need only a few lines of information to create each
-    configuration. Qt installers install and configure qmake.
-    To use one of the other supported build systems, you need to set it up.
-
-    \li \l {Build with CMake}{CMake} is an alternative to qmake for automating the
-    generation of build configurations. For more information, see
-    \l {Setting Up CMake}.
-
-    \li \l {https://mesonbuild.com/}{Meson} is a fast and user-friendly
-    open-source build system that aims to minimize the time developers spend
-    writing or debugging build definitions and waiting for the build system
-    to start compiling code. For more information, see \l {Setting Up Meson}.
-
-    \li \l{Qbs Manual}{Qbs} is an all-in-one build tool that generates a build graph
-    from a high-level project description (like qmake or CMake do) and executes
-    the commands in the low-level build graph (like make does). For more
-    information, see \l{Setting Up Qbs}.
-
-    \endlist
-
-    To export a project to some other build system, such as Microsoft Visual
-    Studio, select \uicontrol Build > \uicontrol {Run Generator}, and select
-    a generator in the list. \QC generates the build files, such as .vcxproj,
-    in the project's build directory. The tool that you use to build the project
-    (qmake or CMake) provides the generators. Their availability depends on the
-    version of the build tool, host platform, and properties of the host system.
-    Also, a JSON compilation database generator is available if the
-    \l{Parsing C++ Files with the Clang Code Model}{Clang Code Model plugin}
-    is enabled (default).
-
-    To change the location of the project directory, and to specify settings
-    for building and running projects, select \uicontrol Edit >
-    \uicontrol Preferences > \uicontrol {Build & Run} > \uicontrol General.
-
-    Specify build and run settings for different target platforms, in the
-    \uicontrol Projects mode. For more information on the options you have,
-    see \l{Specifying Build Settings}.
-
-//! [build systems]
-*/

doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc

@@ -12,9 +12,11 @@
     \page creator-project-creating.html
     \nextpage creator-file-creating.html
 
+    \ingroup creator-explanation-projects
+
     \title Creating Projects
 
-    Creating a project enables you to:
+    Create projects to:
 
     \list
 
@@ -28,32 +30,57 @@
 
     \endlist
 
+    To set up a project, you first have to decide what kind of an application
+    you want to develop: do you want a user interface based on Qt Quick or
+    Qt widgets. Second, you have to choose the language to implement the
+    application logic: C++, JavaScript, or Python.
+
     When you set up a new project in \QC, a wizard guides you step-by-step
     through the process. The wizard templates prompt you to enter the settings
-    that you need for that particular type of project and create
+    that you need for that particular type of project and create the necessary
-    the necessary files for you. You can add your own custom wizards to
+    files for you.
-    standardize the way of adding subprojects and classes to a project.
 
-    Most \QC project wizards enable you to choose the build system to use for
+    \image qtcreator-project-qt-quick.webp {New Project dialog}
+
+    You can add your own custom wizards to standardize the way of adding
+    subprojects and classes to a project. In the \uicontrol {New Project} and
+    \uicontrol {New File} dialogs you can see an icon (1), a display name (2),
+    and a description (3) of the wizard.
+
+    \image qtcreator-custom-wizard.png {Wizard details in the New Project dialog}
+
+    In most project wizards, you can choose the build system to use for
     building the project: qmake, CMake, or Qbs. If you do not get to choose,
     the project uses qmake as the build system.
 
+    \image qtcreator-new-project-build-system-qt-gui.png {Define Build System dialog}
+
     You can use wizards also to create plain C or C++ projects that use
     qmake, Qbs, or CMake, but do not use the Qt library.
 
     In addition, you can import projects as \e {generic projects} that do not
-    use qmake, Qbs, or CMake. This enables you to use \QC as a code editor and
+    use qmake, Qbs, or CMake. Use \QC as a code editor and fully control the
-    to fully control the steps and commands used to build the project.
+    steps and commands used to build the project.
 
-    You can install tools for \l{glossary-device}{devices} as part of Qt distributions.
+    To test applications on \l{glossary-device}{devices}, you can install
+    toolchains for mobile and embedded development as part of Qt distributions.
     The installers create \l{glossary-buildandrun-kit}{kits} and specify build
     and run settings for the installed device types. However, you might need to
     install and configure some additional software on the devices to be able to
     \l{Connecting Devices}{connect} to them from the development PC.
 
-    \include creator-projects-build-systems.qdocinc build systems
+    \sa {Manage Projects}{How-to: Manage Projects}, {Creating Files},
+    {Adding Libraries to Projects}, {Opening Projects},
+    {Adding New Custom Wizards}
+*/
 
-    \section1 Using Project Wizards
+/*!
+    \page creator-how-to-use-project-wizards.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-projects
+
+    \title Use project wizards
 
     To create a new project, select \uicontrol File > \uicontrol{New Project} and
     select the type of your project. The contents of the wizard dialogs depend
@@ -75,7 +102,7 @@
     For example, if you choose to create a Qt Quick application, \QC generates a
     QML file that you can modify in the \uicontrol Edit mode.
 
-    \section1 Selecting Project Type
+    \section1 Select project type
 
     The following table lists the types of wizard templates that you can use
     for creating projects. The \uicontrol {New Project} dialog shows detailed
@@ -101,7 +128,7 @@
                  widgets or widget collections,
                 \l{Qt Quick UI Projects}{Qt Quick UI projects},
                 \l {Creating Tests}{auto-test projects},
-                \l{Adding Subprojects to Projects}{subprojects},
+                \l{Add subprojects to projects}{subprojects},
                 empty qmake projects, or qmake projects for testing
                 code snippets.
         \row
@@ -133,7 +160,28 @@
     For more information about creating Qt Quick projects, see
     \l {Creating Qt Quick Projects}.
 
-    \section1 Specifying Project Contents
+    \section1 Bind keyboard shortcuts to wizards
+
+    If you use a wizard regularly, you can bind a custom keyboard shortcut to
+    it. Triggering this keyboard shortcut directly opens the wizard, so you do
+    not need to navigate to \uicontrol File > \uicontrol {New File} or
+    \uicontrol {New Project}.
+
+    Set keyboard shortcuts for wizards in \uicontrol Edit >
+    \uicontrol Preferences > \uicontrol Environment > \uicontrol Keyboard >
+    \uicontrol Wizard. All wizard actions start with \uicontrol Impl there.
+
+    \sa {Assign keyboard shortcuts}, {Activating Kits for a Project},
+    {Creating Files}, {Creating Projects}
+*/
+
+/*!
+    \page creator-how-to-specify-project-contents.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-projects
+
+    \title Specify project contents
 
     A project can have files that should be:
 
@@ -146,8 +194,8 @@
             to \QC
     \endlist
 
-    \QC displays all files that you declare to be part of the project by the
+    The \l Projects view shows all files that you declare to be part of the
-    project files in the \l Projects view. It sorts the files into categories
+    project in the project files. It sorts the files into categories
     by file type (.cpp, .h, .qrc, and so on). To display additional files, edit
     the project file. Alternatively, you can see all the files in a project
     directory in the \l {File System} view.
@@ -156,7 +204,7 @@
     \l{Searching with the Locator}{locator} and \l{Advanced Search}
     {project-wide search}.
 
-    \section2 CMake Projects
+    \section1 CMake Projects
 
     When using CMake, you can specify additional files for a project by either
     adding them as sources or installing them.
@@ -177,7 +225,7 @@
     Alternatively, to install the files, use the \l {CMake: install command}
     {install} command with the \c FILES or \c DIRECTORY property.
 
-    \section2 qmake Projects
+    \section1 qmake Projects
 
     Use the following variables in the .pro file:
 
@@ -197,24 +245,33 @@
 
     \endcode
 
-    \section1 Adding Subprojects to Projects
+    \sa {Creating Projects}, {Use project wizards}, {Projects}
 
-    In addition to Qt libraries, you can link your application to other
+*/
-    libraries, such as system libraries or your own libraries. Further, your
+
-    own libraries might link to other libraries. To be able to compile your
+/*!
-    project, you must add the libraries to your project. This also enables
+    \page creator-how-to-add-subprojects-to-projects.html
-    code completion and syntax highlighting for the libraries.
+    \previouspage creator-how-tos.html
-    The procedure of adding a library to a project depends on the build
+
+    \ingroup creator-how-to-projects
+
+    \title Add subprojects to projects
+
+    You can link your application to Qt libraries and other libraries, such as
+    system libraries or your own libraries. Further, your own libraries might
+    link to other libraries. To compile your project and benefit from services
+    such as code completion and syntax highlighting, add the libraries to your
+    project. The process of adding a library to a project depends on the build
     system that you use.
 
-    \section2 CMake Projects
+    \section1 CMake projects
 
-    You can add CMakeLists.txt files to any project by using the
+    To add CMakeLists.txt files to any project, use the
     \l{https://cmake.org/cmake/help/latest/command/add_subdirectory.html}
     {add_subdirectory} command. The files can define complete projects that
     you include into the top-level project or any other CMake commands.
 
-    \section2 qmake Projects
+    \section1 qmake projects
 
     When you create a new project and select qmake as the build system,
     you can add it to another project as a subproject in the
@@ -222,19 +279,26 @@
     must specify that qmake uses the \c subdirs \l{TEMPLATE}{template} to
     build the project.
 
-    To create a root project, select \uicontrol File >
+    To create a root project:
-    \uicontrol {New Project} > \uicontrol {Other Project} >
-    \uicontrol {Subdirs Project} > \uicontrol Choose.
 
-    On the \uicontrol Summary page, select \uicontrol {Finish & Add Subproject} to create
+    \list 1
-    the root project and to add another project, such as a C++ library.
+        \li Select \uicontrol File > \uicontrol {New Project} >
+            \uicontrol {Other Project} > \uicontrol {Subdirs Project} >
+            \uicontrol Choose.
+
+        \li On the \uicontrol Summary page, select
+            \uicontrol {Finish & Add Subproject} to create
+            the root project and to add another project, such as a C++ library.
+    \endlist
 
     The wizard creates a project file (.pro) that defines a \c subdirs template
     and the subproject that you add as a value of the \l{Variables#subdirs}
     {SUBDIRS variable}. It also adds all the necessary files for the subproject.
 
+    \section2 Add subprojects to the root project
+
     To create more subprojects, right-click the project name in the
-    \uicontrol Projects view to open the context menu, and select
+    \l Projects view to open the context menu, and select
     \uicontrol {New Subproject}. Follow the steps in the
      \uicontrol {New Subproject} wizard to create a subproject.
 
@@ -244,31 +308,15 @@
     \uicontrol {Add Existing Projects} in the context menu.
     In the file browser dialog, locate your subproject.
 
+    \section2 Remove subprojects
+
     To remove subprojects, right-click the project name in the \uicontrol Projects
     view, and select \uicontrol {Remove Subproject} in the context menu.
 
-    To specify dependencies, use the \uicontrol{Add Library} wizard. For more
+    \section2 Specify dependencies
-    information, see \l{Adding Libraries to Projects}.
 
-    \section1 Binding Keyboard Shortcuts to Wizards
+    To specify dependencies, use the \uicontrol{Add Library} wizard.
-
-    If you use a wizard regularly, you can bind a custom keyboard shortcut to
-    it. Triggering this keyboard shortcut directly opens the wizard, so you do
-    not need to navigate to \uicontrol File > \uicontrol {New File} or
-    \uicontrol {New Project}.
-
-    Set keyboard shortcuts for wizards in \uicontrol Edit >
-    \uicontrol Preferences > \uicontrol Environment > \uicontrol Keyboard >
-    \uicontrol Wizard. All wizard actions start with \uicontrol Impl there.
-
-    \section1 Related Topics
-
-    \list
-        \li  \l{Creating Files}
-        \li  \l{Opening Projects}
-        \li  \l{Adding Libraries to Projects}
-        \li  \l{Adding New Custom Wizards}
-        \li  \l{Build Systems}
-    \endlist
 
+    \sa {Creating Projects}, {Use project wizards},
+    {Adding Libraries to Projects}
 */

doc/qtcreator/src/projects/creator-only/creator-projects-overview.qdoc

@@ -1,4 +1,4 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 // **********************************************************************
@@ -16,9 +16,9 @@
 
     \image front-projects.png
 
-    One of the major advantages of \QC is that it allows a team of designers and
+    You can share projects with other designers and developers across different
-    developers to share a project across different development platforms with a
+    development platforms with a common tool for design, development, and
-    common tool for design, development, and debugging.
+    debugging.
 
     \list
 
@@ -40,7 +40,7 @@
 
             Installation programs and project wizards create default
             configurations for \QC and your projects. You can modify
-            the settings in the Projects mode.
+            the settings in the \uicontrol Projects mode.
 
         \li \l{Managing Sessions}
 
@@ -50,10 +50,6 @@
 
     \endlist
 
-    \section1 Related Topics
+    \sa {Build Systems}
-
-    \list
-        \li \l{Build Systems}
-    \endlist
 
 */

doc/qtcreator/src/projects/creator-only/creator-projects-settings-dependencies.qdoc

@@ -45,7 +45,7 @@
     specify for the projects loaded in the session.
 
     \note You cannot use this view to specify subprojects for projects.
-    For more information on how to add subprojects, see \l{Adding Subprojects
+
-    to Projects}.
+    \sa {Add subprojects to projects}
 
 */

doc/qtcreator/src/python/creator-python-run.qdocinc

@@ -6,7 +6,7 @@
     \section1 Running Python Projects
 
     You can execute Qt for Python applications directly from \QC. If you
-    used the \l{Using Project Wizards}{new project wizard}
+    used the \l{Use project wizards}{new project wizard}
     to create the application project, the \c main.py file is automatically
     executed when you select the \uicontrol Run button.
 

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -277,7 +277,11 @@
                     \li Manage Projects
                         \list
                             \li \l {Add a license header template for C++ code}
+                            \li \l {Add subprojects to projects}
                             \li \l {Develop Qt for Python applications}
+                            \li \l {Select the build system}
+                            \li \l {Specify project contents}
+                            \li \l {Use project wizards}
                         \endlist
                     \li Use \QC
                         \list

doc/qtcreator/src/user-interface/creator-projects-view.qdoc

@@ -146,7 +146,7 @@
     enables you to specify exactly where to place a new file in the build system.
 
     If you cannot see some files, you might have to declare them as part of the
-    project. For more information, see \l{Specifying Project Contents}.
+    project. For more information, see \l{Specify project contents}.
 
     If the project is under version control, you might see information
     from the version control system in brackets after the project name.

doc/qtcreator/src/vcs/creator-only/creator-vcs-gitlab.qdoc

@@ -92,7 +92,7 @@
     open, select \uicontrol File > \uicontrol {New Project} >
     \uicontrol {Import Project} > \uicontrol {Import Existing Project} to
     import the project as a generic project. For more information, see
-    \l {Using Project Wizards}.
+    \l {Use project wizards}.
 
     \section1 Linking Projects with GitLab