Doc: All overviews list categorization

The \generate list names are added for each categorized section with
some explanation. Here, calling the overviews as
explanations-(name of the section). The idea is to give general terms
instead of specific phrases like 'core' etc, for better understanding.

Allow two warnings for \generatelist commands as the related \group
pages live in modules external to qtdoc and are not loaded when
testing documentation in the CI.

Task-number: QTBUG-115347
Pick-to: 6.5 6.6
Change-Id: Ia8307d42fdb137808ae75cb9bcfeb58de30ba550
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

doc/config/qtdoc.qdocconf

@@ -100,5 +100,7 @@ manifestmeta.examplecategories = "Application Examples" \
 # Include 'Qt for Education' pages
 include(../edu/config/qtforeducation.qdocconf)
 
-# Enforce zero documentation warnings
+# doc/src/overviews.qdoc:
-warninglimit = 0
+#   (qdoc) warning: '\generatelist explanations-webtechnologies' no such group
+#   (qdoc) warning: '\generatelist explanations-positioning' no such group
+warninglimit = 2

doc/src/connectivity.qdoc

@@ -5,7 +5,7 @@
 \page topics-network-connectivity.html
 \title Networking and Connectivity
 \brief Qt's network and connectivity features.
-\ingroup explanation
+\ingroup explanations-networkingandconnectivity
 
 Qt provides classes for both high-level and low-level network communication,
 classes for web integration, and classes for inter-process communication (IPC).

doc/src/core.qdoc

@@ -5,7 +5,7 @@
 \page topics-core.html
 \title Core Internals
 \brief Qt's core topics
-\ingroup explanation
+\ingroup explanations-basics
 
 Qt contains a rich set of fundamental enablers, mainly from the \l{Qt Core}
 module. Qt uses these enablers to provide higher-level UI and application

doc/src/datainputoutput.qdoc

@@ -5,7 +5,7 @@
 \page topics-data-io.html
 \title Data Input Output
 \brief Qt's data input output
-\ingroup explanation
+\ingroup explanations-dataprocessingandio
 
 This page provides an overview of various ways of retrieving and saving data using Qt.
 

doc/src/developmenttools.qdoc

@@ -5,7 +5,7 @@
 \page topics-app-development.html
 \title Development Tools
     \brief Qt tools for application development.
-    \ingroup explanation
+    \ingroup explanations-tools
 
     Qt is designed for developing applications and user interfaces once and
     deploying them across several desktop and mobile operating systems.

doc/src/frameworks-technologies/accessible.qdoc

@@ -11,11 +11,10 @@
     \page accessible.html
     \title Accessibility
     \brief How to make your applications accessible to those with disabilities.
+    \ingroup explanations-accessibility
 
     \nextpage Accessibility for QWidget Applications
 
-    \ingroup best-practices
-
     \tableofcontents
 
     \section1 Introduction

doc/src/frameworks-technologies/desktop-integration.qdoc

@@ -8,6 +8,7 @@
 
     \ingroup best-practices
     \ingroup qt-gui-concepts
+    \ingroup explanations-platforms
 
     Qt applications behave well in the user's desktop environment, but certain
     integrations require additional, and sometimes platform specific, techniques.

doc/src/graphics.qdoc

@@ -6,7 +6,7 @@
 \title Graphics
 \keyword topics-graphics
 \brief Qt's graphics features
-\ingroup explanation
+\ingroup explanations-graphicsandmultimedia
 
 Cross-platform applications can use Qt to display graphical elements. Qt
 abstracts the platforms' underlying graphics APIs so that developers can focus

doc/src/howtos/exceptionsafety.qdoc

@@ -5,6 +5,7 @@
     \page exceptionsafety.html
     \title Exception Safety
     \ingroup best-practices
+    \ingroup explanations-basics
     \brief A guide to exception safety in Qt.
 
     \b {Preliminary warning}: Exception safety is not feature complete!

doc/src/howtos/scalabilityintro.qdoc

@@ -6,8 +6,7 @@
     \page scalability.html
     \brief How to develop applications that scale well on devices with different
     screen configurations and UI conventions.
-
+    \ingroup explanations-accessibility
-    \ingroup best-practices
 
     When you develop applications for several different mobile device platforms,
     you face the following challenges:

doc/src/howtos/unix-signal-handlers.qdoc

@@ -7,6 +7,7 @@
     \brief You can't. But don't despair, there is a way...
 
     \ingroup best-practices
+    \ingroup explanations-platforms
 
     You \e can't call Qt functions from Unix signal handlers. The
     standard POSIX rule applies: You can only call async-signal-safe

doc/src/internationalization/i18n.qdoc

@@ -7,7 +7,7 @@
     \brief Qt's support for internationalization and multiple languages.
     \nextpage Writing Source Code for Translation
 
-    \ingroup explanation
+    \ingroup explanations-accessibility
     \keyword internationalization
     \keyword i18n
 

doc/src/mobile.qdoc

@@ -5,7 +5,7 @@
     \page mobiledevelopment.html
     \title Mobile Development
     \brief Development for mobile devices.
-    \ingroup explanation
+    \ingroup explanations-platforms
 
     Qt supports development and deployment of mobile applications.
 

doc/src/overviews.qdoc

@@ -7,7 +7,92 @@
     \title All Overviews
 
     \section1 Overviews
-    \generatelist explanation
+    \l {Introduction to Qt}
+
+    \section1 Programming Languages
+    You can develop Qt applications using one or a combination of the following languages:
+
+    \l {Qt Languages}
+    \list
+        \li C++
+        \li QML
+        \li Python
+        \li JavaScript
+    \endlist
+
+    \section2 QML and C++
+
+    \generatelist explanations-programminglanguages
+
+    \section1 Platforms
+    Develop Qt applications on macOS, Linux, and Windows desktop platforms.
+    Qt is platform-independent, which means you can compile same code base for other
+    target platforms.
+    \generatelist explanations-platforms
+
+    \section1 Basics
+    Learn the Qt basics that define the foundation of Qt.
+
+    \generatelist explanations-basics
+
+    \section1 UI
+    Use the Qt Quick and Qt Widget UI technology. Qt Quick interfaces are fluid,
+    dynamic, and are best on touch interfaces.
+    Qt Widgets are for creating complex desktop applications. You can create Qt Quick
+    and Qt Widgets interfaces with the target platform's native look and feel.
+
+    \generatelist explanations-ui
+
+    \section1 Graphics and Multimedia
+    Display graphical elements and handle multimedia content.
+    Qt abstracts the target platforms' underlying graphics APIs so that you can
+    focus on writing the application code.
+    Play back audio and video files and render them on screen, as well as
+    record audio and video from the system's cameras and microphones.
+
+    \generatelist explanations-graphicsandmultimedia
+
+    \section1 Data processing and I/O
+    Retrieve and store data in different formats.
+
+    \generatelist explanations-dataprocessingandio
+
+    \section1 Networking and Connectivity
+    Develop applications that communicate with Web services and exchange data (JSON or CBOR)
+    with applications on other devices.
+
+    In addition, Qt applications can use remote objects or gRPC and protobuf to
+    communicate with service endpoints.
+
+    \generatelist explanations-networkingandconnectivity
+
+    \section1 Web Technologies
+    Embed content from the World Wide Web into your Qt applications on platforms
+    that do not have a native web engine.
+
+    Alternatively, you can create a web channel for peer-to-peer communication
+    between a server and a client.
+
+    \generatelist explanations-webtechnologies
+
+    \section1 Tools
+    Qt installations contain Qt libraries, examples, documentation, and the necessary
+    development tools, such as the Qt Creator integrated development environment (IDE)
+    and Qt Design Studio for developing Qt Quick Applications.
+
+    \generatelist explanations-tools
+
+    \section1 Accessibility
+    Write accessible software by letting users scale the UI, change font size and
+    color contrast, use the keyboard for navigation, have UI text read aloud with
+    a synthesized voice, and change the UI language.
+
+    \generatelist explanations-accessibility
+
+    \section1 Positioning
+
+    \generatelist explanations-positioning
+
 
 */
 

doc/src/platformintegration/platformintegration.qdoc

@@ -5,7 +5,7 @@
     \page platform-integration.html
     \title Platform Integration
     \brief Integrating Qt with the native platform.
-    \ingroup explanation
+    \ingroup explanations-platforms
 
     Qt's main strength as a cross-platform toolkit for application development
     is removing the need for duplicating the application code for each target

doc/src/platforms/android/android-how-it-works.qdoc

@@ -6,7 +6,7 @@
 \title Qt for Android: How It Works
 \brief An overview of architecture, toolchain, and other useful information.
 \ingroup androidplatform
-\ingroup explanation
+\ingroup explanations-platforms
 
 
 If you're a developer looking for a high level overview of how Qt supports the

doc/src/platforms/configure-linux-device.qdoc

@@ -5,7 +5,7 @@
     \page configure-linux-device.html
     \title Configure an Embedded Linux Device
     \brief Provides information about how to configure an Embedded Linux device in Qt.
-    \ingroup explanation
+    \ingroup explanations-platforms
 
     Cross-compiling Qt for a given device requires a \b toolchain and a \b sysroot. The
     toolchain is expected to contain a version of gcc, or another compiler, and associated

doc/src/qmlapp/applicationdevelopers.qdoc

@@ -5,7 +5,7 @@
 \page qmlapplications.html
 \title QML Applications
 \brief Essential documentation for QML application developers
-\ingroup explanation
+\ingroup explanations-programminglanguages
 
 QML is a declarative language that allows user interfaces to be described in
 terms of their visual components and how they interact and relate with one

doc/src/qmlapp/usecases/layouts.qdoc

@@ -4,7 +4,7 @@
 \page qtquick-usecase-layouts.html
 \title Use Case - Positioners and Layouts In QML
 \brief Example of how to create layouts for visual components in a QML application
-\ingroup explanation
+\ingroup explanations-programminglanguages
 
 There are several ways to position items in QML.
 

doc/src/testing.qdoc

@@ -5,6 +5,7 @@
 \page testing-and-debugging.html
 \title Testing and Debugging
 \brief Writing unit tests and debugging with Qt
+\ingroup explanations-platforms
 
 Qt provides various functionality to help you develop high quality code. There
 are features that assist in debugging to track down bugs, and testing facilities

doc/src/userinterfaces.qdoc

@@ -5,7 +5,7 @@
 \page topics-ui.html
 \title User Interfaces
 \brief Qt's technologies for Creating User Interfaces
-\ingroup explanation
+\ingroup explanations-ui
 
 The Qt framework's main user interface technologies are \b{Qt Quick}
 and \b{Qt Widgets}. Qt Quick interfaces are fluid, dynamic, and are best

doc/src/wayland-and-qt.qdoc

@@ -5,7 +5,7 @@
   \page wayland-and-qt.html
   \title Wayland and Qt
   \brief An overview of the Wayland protocol and how it fits into Qt.
-  \ingroup explanation
+  \ingroup explanations-platforms
 
   Wayland was developed as an alternative to X11 on Linux. Its main purpose is to manage how
   the content of applications is displayed together on a shared screen, and how a user can

doc/src/xml-overview.qdoc

@@ -5,7 +5,7 @@
     \page xml-processing.html
     \title XML Processing
     \brief An Overview of the XML processing facilities in Qt.
-    \ingroup explanation
+    \ingroup explanations-dataprocessingandio
 
     Qt provides two sets of APIs to read and write well-formed XML: \l{XML Streaming}{stream based} and
     \l{Working with the DOM Tree}{DOM based}.