From e5020dd289e18ad5124b0f68b51b8cdb6e06072e Mon Sep 17 00:00:00 2001 From: Jaishree Vyas Date: Tue, 25 Jul 2023 18:35:04 +0200 Subject: [PATCH] Doc: All overviews list categorization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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ö --- doc/config/qtdoc.qdocconf | 6 +- doc/src/connectivity.qdoc | 2 +- doc/src/core.qdoc | 2 +- doc/src/datainputoutput.qdoc | 2 +- doc/src/developmenttools.qdoc | 2 +- .../frameworks-technologies/accessible.qdoc | 3 +- .../desktop-integration.qdoc | 1 + doc/src/graphics.qdoc | 2 +- doc/src/howtos/exceptionsafety.qdoc | 1 + doc/src/howtos/scalabilityintro.qdoc | 3 +- doc/src/howtos/unix-signal-handlers.qdoc | 1 + doc/src/internationalization/i18n.qdoc | 2 +- doc/src/mobile.qdoc | 2 +- doc/src/overviews.qdoc | 87 ++++++++++++++++++- .../platformintegration.qdoc | 2 +- .../android/android-how-it-works.qdoc | 2 +- doc/src/platforms/configure-linux-device.qdoc | 2 +- doc/src/qmlapp/applicationdevelopers.qdoc | 2 +- doc/src/qmlapp/usecases/layouts.qdoc | 2 +- doc/src/testing.qdoc | 1 + doc/src/userinterfaces.qdoc | 2 +- doc/src/wayland-and-qt.qdoc | 2 +- doc/src/xml-overview.qdoc | 2 +- 23 files changed, 111 insertions(+), 22 deletions(-) diff --git a/doc/config/qtdoc.qdocconf b/doc/config/qtdoc.qdocconf index a577da891..44bc8bf5a 100644 --- a/doc/config/qtdoc.qdocconf +++ b/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 -warninglimit = 0 +# doc/src/overviews.qdoc: +# (qdoc) warning: '\generatelist explanations-webtechnologies' no such group +# (qdoc) warning: '\generatelist explanations-positioning' no such group +warninglimit = 2 diff --git a/doc/src/connectivity.qdoc b/doc/src/connectivity.qdoc index dee38f22a..a58d01614 100644 --- a/doc/src/connectivity.qdoc +++ b/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). diff --git a/doc/src/core.qdoc b/doc/src/core.qdoc index 72faa58ca..e167102f8 100644 --- a/doc/src/core.qdoc +++ b/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 diff --git a/doc/src/datainputoutput.qdoc b/doc/src/datainputoutput.qdoc index 97cb49513..36b001d64 100644 --- a/doc/src/datainputoutput.qdoc +++ b/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. diff --git a/doc/src/developmenttools.qdoc b/doc/src/developmenttools.qdoc index c0203f91e..43af3ca78 100644 --- a/doc/src/developmenttools.qdoc +++ b/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. diff --git a/doc/src/frameworks-technologies/accessible.qdoc b/doc/src/frameworks-technologies/accessible.qdoc index 28cc0196a..acb7dd20f 100644 --- a/doc/src/frameworks-technologies/accessible.qdoc +++ b/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 diff --git a/doc/src/frameworks-technologies/desktop-integration.qdoc b/doc/src/frameworks-technologies/desktop-integration.qdoc index 1a9951fbe..88bec410a 100644 --- a/doc/src/frameworks-technologies/desktop-integration.qdoc +++ b/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. diff --git a/doc/src/graphics.qdoc b/doc/src/graphics.qdoc index f5428fa72..5f0d13a65 100644 --- a/doc/src/graphics.qdoc +++ b/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 diff --git a/doc/src/howtos/exceptionsafety.qdoc b/doc/src/howtos/exceptionsafety.qdoc index a2e660643..2585da11b 100644 --- a/doc/src/howtos/exceptionsafety.qdoc +++ b/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! diff --git a/doc/src/howtos/scalabilityintro.qdoc b/doc/src/howtos/scalabilityintro.qdoc index 537d6237e..4a427a6ce 100644 --- a/doc/src/howtos/scalabilityintro.qdoc +++ b/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 best-practices + \ingroup explanations-accessibility When you develop applications for several different mobile device platforms, you face the following challenges: diff --git a/doc/src/howtos/unix-signal-handlers.qdoc b/doc/src/howtos/unix-signal-handlers.qdoc index 31dc36611..45331a23a 100644 --- a/doc/src/howtos/unix-signal-handlers.qdoc +++ b/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 diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index 1b0e625c8..ede019c1e 100644 --- a/doc/src/internationalization/i18n.qdoc +++ b/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 diff --git a/doc/src/mobile.qdoc b/doc/src/mobile.qdoc index 8bc37ee3c..663e4d89b 100644 --- a/doc/src/mobile.qdoc +++ b/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. diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index 4fb30ea6b..5b3494bf3 100644 --- a/doc/src/overviews.qdoc +++ b/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 + */ diff --git a/doc/src/platformintegration/platformintegration.qdoc b/doc/src/platformintegration/platformintegration.qdoc index 5db410c9d..86cd50391 100644 --- a/doc/src/platformintegration/platformintegration.qdoc +++ b/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 diff --git a/doc/src/platforms/android/android-how-it-works.qdoc b/doc/src/platforms/android/android-how-it-works.qdoc index b08c26cca..d8d1ece00 100644 --- a/doc/src/platforms/android/android-how-it-works.qdoc +++ b/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 diff --git a/doc/src/platforms/configure-linux-device.qdoc b/doc/src/platforms/configure-linux-device.qdoc index 16f9e969e..f511c55d1 100644 --- a/doc/src/platforms/configure-linux-device.qdoc +++ b/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 diff --git a/doc/src/qmlapp/applicationdevelopers.qdoc b/doc/src/qmlapp/applicationdevelopers.qdoc index 1817c7d6d..ef5415ef0 100644 --- a/doc/src/qmlapp/applicationdevelopers.qdoc +++ b/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 diff --git a/doc/src/qmlapp/usecases/layouts.qdoc b/doc/src/qmlapp/usecases/layouts.qdoc index b53fa43e0..fb5d95913 100644 --- a/doc/src/qmlapp/usecases/layouts.qdoc +++ b/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. diff --git a/doc/src/testing.qdoc b/doc/src/testing.qdoc index 8de4edace..aac2348f0 100644 --- a/doc/src/testing.qdoc +++ b/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 diff --git a/doc/src/userinterfaces.qdoc b/doc/src/userinterfaces.qdoc index 19bf90767..36a34ddf6 100644 --- a/doc/src/userinterfaces.qdoc +++ b/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 diff --git a/doc/src/wayland-and-qt.qdoc b/doc/src/wayland-and-qt.qdoc index becbdaac5..8be5ba33b 100644 --- a/doc/src/wayland-and-qt.qdoc +++ b/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 diff --git a/doc/src/xml-overview.qdoc b/doc/src/xml-overview.qdoc index 3ff131de1..a685f62fb 100644 --- a/doc/src/xml-overview.qdoc +++ b/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}.