Document how to use CMake on Qt Core, Qt GUI's central pages

Add documentation on how to use a module from CMake, alongside
the existing documentation about qmake. Separate generic info
from module-specific examples, to make it possible to use one
include file in all modules.

While at it, also remove the mentioning of the central include;
it is not something we should actively advocate anymore. Instead,
the documentation of every class gives the correct include to use.

Task-number: QTBUG-73058
Change-Id: I6b3c0e5ea218dd9c06a491c8fb799a7fcf42dd92
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

doc/global/includes/module-use.qdocinc

@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [using qt module]
+
+    \section1 Using the Module
+
+    Using a Qt module requires linking against the module library, either
+    directly or through other dependencies. Several build tools have dedicated
+    support for this, including \l{CMake Documentation}{CMake} and
+    \l{qmake}.
+
+    \section2 Building with CMake
+
+    Use the \c{find_package()} command to locate the needed module components in
+    the \c{Qt5} package:
+
+//! [using qt module]
+
+
+//! [building with qmake]
+
+    \section2 Building with qmake
+
+    To configure the module for building with qmake, add the module as a value
+    of the \c QT variable in the project's .pro file:
+
+//! [building with qmake]

doc/global/qt-html-templates-offline.qdocconf

@@ -16,6 +16,8 @@ HTML.extraimages += template/images/ico_out.png \
                     template/images/bullet_sq.png \
                     template/images/bgrContent.png
 
+sourcedirs += includes
+
 #specify which files in the output directory should be packed into the qch file.
 qhp.extraFiles +=   style/offline.css \
                     images/ico_out.png \

doc/global/qt-html-templates-online.qdocconf

@@ -7,4 +7,5 @@ include(html-footer-online.qdocconf)
 #uncomment if navigation bar is not wanted
 #HTML.nonavigationbar      = "true"
 
-sourcedirs += includes-online
+sourcedirs += includes-online \
+              includes

src/corelib/doc/snippets/code/doc_src_qtcore.cpp

@@ -1,53 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** BSD License Usage
-** Alternatively, you may use this file under the terms of the BSD license
-** as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-**   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
-**   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
-**   * Neither the name of The Qt Company Ltd nor the names of its
-**     contributors may be used to endorse or promote products derived
-**     from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-//! [0]
-#include <QtCore>
-//! [0]

src/corelib/doc/snippets/overview/using-qt-core.cmake

@@ -0,0 +1,2 @@
+find_package(Qt5 COMPONENTS Core REQUIRED)
+target_link_libraries(mytarget Qt5::Core)

src/corelib/doc/src/qtcore-index.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -31,17 +31,9 @@
 
     \brief The Qt Core module is part of Qt's essential modules.
 
-    \section1 Getting Started
-    All other Qt modules rely on this module. To include the
-    definitions of the module's classes, use the following directive:
-
-    \snippet code/doc_src_qtcore.cpp 0
-
-    If you use \l qmake to build your projects, Qt Core is included by default.
-
     \section1 Core Functionalities
 
-    Qt adds these features to C++:
+    Qt Core adds these features to C++:
 
     \list
     \li a very powerful mechanism for seamless object communication called
@@ -61,6 +53,15 @@
     \li \l{Signals & Slots}
     \endlist
 
+    \include module-use.qdocinc using qt module
+    \quotefile overview/using-qt-core.cmake
+
+    See also the \l[QtDoc]{Building with CMake} overview.
+
+    \section2 Building with qmake
+
+    If you use \l qmake to build your projects, Qt5Core is linked by default.
+
     \section1 Threading and Concurrent Programming
 
     Qt provides thread support in the form of platform-independent \l{Threading

src/corelib/doc/src/qtcore.qdoc

@@ -33,12 +33,5 @@
 
     \brief Provides core non-GUI functionality.
 
-    All other Qt modules rely on this module. To include the
+    All other Qt modules rely on this module.
-    definitions of the module's classes, use the following directive:
-
-    \snippet code/doc_src_qtcore.cpp 0
-
-    If you use \l qmake to build your projects, \l{Qt Core} is included by
-    default.
-
 */

src/gui/doc/snippets/code/doc_src_qtgui.pro

@@ -1,7 +1,3 @@
-#! [0]
-#include <QtGui>
-#! [0]
-
 #! [1]
 QT -= gui
 #! [1]

src/gui/doc/snippets/overview/using-qt-gui.cmake

@@ -0,0 +1,2 @@
+find_package(Qt5 COMPONENTS Gui REQUIRED)
+target_link_libraries(mytarget Qt5::Gui)

src/gui/doc/src/qtgui.qdoc

@@ -40,18 +40,6 @@
     These classes are used internally by Qt's user interface technologies
     and can also be used directly, for instance to write applications using
     low-level OpenGL ES graphics APIs.
-
-    To include the definitions of the module's classes, use the
-    following directive:
-
-    \snippet code/doc_src_qtgui.pro 0
-
-    \if !defined(qtforpython)
-    If you use \l qmake to build your projects, \l{Qt GUI} is included by
-    default. To disable Qt GUI, add the following line to your \c .pro file:
-
-    \snippet code/doc_src_qtgui.pro 1
-    \endif
 */
 
 /*!
@@ -69,14 +57,15 @@
     higher level API's, like Qt Quick, that are much more suitable
     than the enablers found in the Qt GUI module.
 
-    \section1 Getting Started
-
-    To include the definitions of the module's classes, use the
-    following directive:
-
-    \snippet code/doc_src_qtgui.pro 0
-
     \if !defined(qtforpython)
+
+    \include module-use.qdocinc using qt module
+    \quotefile overview/using-qt-gui.cmake
+
+    See also the \l[QtDoc]{Building with CMake} overview.
+
+    \section2 Building with qmake
+
     If you use \l qmake to build your projects, Qt GUI is included by
     default. To disable Qt GUI, add the following line to your \c .pro file: