Doc: Divide documentation into submodules

QDoc in Qt 5.11 will use Clang (libclang) to parse C++ documentation.
In order to do that, Clang needs to have the include paths available
when parsing source; qmake provides that information to QDoc but only
when the documentation project is located under the correct module
(source) path.

By having dedicated doc projects for Qt 3D Core, Render, Input, etc.
the number of documentation warnings is signicantly reduced. A
top-level 'Qt 3D' project is still kept, and contains the landing page,
overview, examples, and top-level 'C++ classes' and 'QML types' pages
that list all types documented across all Qt 3D submodules.

Change-Id: Id5936de36f31c2a8764a64e1e9d7ae0d10e8ab14
Reviewed-by: Martin Smith <martin.smith@qt.io>

3 files changed, 121 insertions, 0 deletions

diff --git a/src/logic/doc/qt3dlogic.qdocconf b/src/logic/doc/qt3dlogic.qdocconf
new file mode 100644
index 000000000..8f7196991
--- /dev/null
+++ b/src/logic/doc/qt3dlogic.qdocconf
@@ -0,0 +1,43 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+include(../../doc/qt3d-config.qdocconf)
+
+project                 = Qt3DLogic
+description             = Qt 3D Logic Reference Documentation
+version                 = $QT_VERSION
+
+qhp.projects            = Qt3DLogic
+
+qhp.Qt3DLogic.file                = qt3dlogic.qhp
+qhp.Qt3DLogic.namespace           = org.qt-project.qt3dlogic.$QT_VERSION_TAG
+qhp.Qt3DLogic.virtualFolder       = qt3dlogic
+qhp.Qt3DLogic.indexTitle          = Qt 3D Logic
+qhp.Qt3DLogic.indexRoot           =
+
+qhp.Qt3DLogic.filterAttributes                   = qt3dlogic $QT_VERSION qtrefdoc
+qhp.Qt3DLogic.customFilters.Qt.name              = Qt3DLogic $QT_VERSION
+qhp.Qt3DLogic.customFilters.Qt.filterAttributes  = qt3dlogic $QT_VERSION
+
+qhp.Qt3DLogic.subprojects                    = classes qmltypes
+
+qhp.Qt3DLogic.subprojects.classes.title      = C++ Classes
+qhp.Qt3DLogic.subprojects.classes.indexTitle = Qt 3D Logic C++ Classes
+qhp.Qt3DLogic.subprojects.classes.selectors  = class doc:headerfile
+qhp.Qt3DLogic.subprojects.classes.sortPages  = true
+
+qhp.Qt3DLogic.subprojects.qmltypes.title      = QML Types
+qhp.Qt3DLogic.subprojects.qmltypes.indexTitle = Qt 3D Logic QML Types
+qhp.Qt3DLogic.subprojects.qmltypes.selectors  = qmltype
+qhp.Qt3DLogic.subprojects.qmltypes.sortPages  = true
+
+tagfile                 = qt3dlogic.tags
+
+depends                 += qtcore qtgui qtqml qtquick qtdoc qmake
+
+# dependencies to other Qt 3D modules
+depends                 += qt3d qt3dcore qt3drender qt3dinput \
+                           qt3dextras qt3danimation qt3dscene2d
+
+sourcedirs  += ..
+headerdirs  += ..
+imagedirs   += images
+exampledirs += snippets
diff --git a/src/logic/doc/src/qt3dlogic-module.qdoc b/src/logic/doc/src/qt3dlogic-module.qdoc
new file mode 100644
index 000000000..db21e050f
--- /dev/null
+++ b/src/logic/doc/src/qt3dlogic-module.qdoc
@@ -0,0 +1,76 @@
+/****************************************************************************
+**
+** 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: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$
+**
+****************************************************************************/
+
+/*!
+    \module Qt3DLogic
+    \title Qt 3D Logic C++ Classes
+    \keyword Qt 3D Logic
+    \brief The Qt 3D Logic module enables synchronizing frames with the Qt 3D
+    backend.
+    \ingroup modules
+    \ingroup qt3d-modules
+    \qtvariable 3dlogic
+
+    To use classes from this module, add this directive into the C++ files:
+
+    \code
+       #include <Qt3DLogic>
+    \endcode
+
+    To link against the corresponding C++ libraries, add the following to your qmake project file:
+
+    \badcode
+       QT += 3dLogic
+    \endcode
+
+*/
+
+/*!
+    \namespace Qt3DLogic
+    \inmodule Qt3DLogic
+    \ingroup qt3d-namespaces
+
+    \brief Contains classes that enable frame synchronization.
+*/
+
+/*!
+   \qmlmodule Qt3D.Logic 2.0
+   \title Qt 3D Logic QML Types
+   \ingroup qmlmodules
+   \ingroup qt3d-qmlmodules
+
+   \brief Provides QML types to synchronize frames with the 3D backend.
+
+   To import and use the module's QML types, use the following statement:
+
+   \badcode
+   import Qt3D.Logic 2.0
+   \endcode
+
+   \section1 QML Types
+*/
+
diff --git a/src/logic/logic.pro b/src/logic/logic.pro
index 584b9af4b..2fd73391c 100644
--- a/src/logic/logic.pro
+++ b/src/logic/logic.pro
@@ -13,4 +13,6 @@ gcov {
 
 include(logic.pri)
 
+QMAKE_DOCS = $$PWD/doc/qt3dlogic.qdocconf
+
 load(qt_module)