QDoc manual: Refer to correct minimal configuration

The QDoc manual contains documentation about the configuration of QDoc
documentation projects. A minimal configuration file is part of this.

As QDoc has evolved over time, so has the requirements for the
configuration file. However, QDoc's manual hasn't kept up with the
changes; the page describing a minimal `.qdocconf`-file is from before
QDoc moved from qtbase.git into qttools.git (October 2015). A minimal
configuration file, `examples/minimum.qdocconf`, is also part of QDoc's
documentation. This was turned into copypasta in 2018. However, the
outdated documentation page was still retained, such that the QDoc
manual links users to a minimal configuration that is either useless,
or usable.

This patch removes the outdated configuration file page, and updates the
link to this page such that the documentation will refer to the minimal
configuration file (as is done elsewhere). This reduces the maintenance
burden of the QDoc manual, as there's now only one minimal example. It
also ensures that users will find helpful information when perusing the
documentation for QDoc.

Furthermore, the minimal configuration file that is kept is modified to
ensure users can copy the contents into their own configuration and
successfully run QDoc to build the documentation project. This involves
the following changes:

- Add the missing `project` configuration setting, as QDoc will bail
  withouth it.
- Add a simple `includepaths` block, as this may be confusing for new
  users.
- Add a `warninglimit` block. Although strictly speaking not required
  in a minimal `.qdocconf`, it can be a useful tool when building a new
  documentation set.
- Reflow some text, make sure it's more in line with QDoc anno 2023.

Fixes: QTBUG-115602
Change-Id: Iabca9c538ae303dd4da589b46f11e50b321d4291
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
(cherry picked from commit 746cfebb0e0ca2d6ae94c2d82dfc85bb1c228575)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 30 insertions, 85 deletions

diff --git a/src/qdoc/qdoc/doc/examples/minimum.qdocconf b/src/qdoc/qdoc/doc/examples/minimum.qdocconf
index 8f53ffc11..fca0cd757 100644
--- a/src/qdoc/qdoc/doc/examples/minimum.qdocconf
+++ b/src/qdoc/qdoc/doc/examples/minimum.qdocconf
@@ -1,10 +1,16 @@
-# QDoc is a tool that constantly evolves to suit our needs,
-# and there are some compatibility issues between old and new
-# practices. For that reason, any QDoc configuration file needs to
-# include compat.qdocconf.
+# QDoc is a tool that constantly evolves and there may be compatibility issues
+# between old and new practices. For that reason, QDoc configuration files in
+# the Qt Project includes compat.qdocconf:
 #include(compat.qdocconf)
 
-# QDoc needs lists of file extensions to know which files to process in
+# Give the documentation project a title:
+project = My documentation project
+
+# Pass additional include paths to QDoc when parsing C++ code for documentation
+# comments.
+#includepaths += -I/some/path
+
+# QDoc needs a lists of file extensions to know which files to process in
 # different situations. Uncomment the following include statement to get
 # a pre-defined list of file extensions.
 #include(fileextensions.qdocconf)
@@ -13,24 +19,28 @@
 headers.fileextensions  = "*.h *.hpp"
 sources.fileextensions  = "*.cpp *.qml *.qdoc"
 
-# The outputdir variable specifies the directory
-# where QDoc will put the generated documentation.
-outputdir   = html
+# The outputdir variable specifies the directory where QDoc places the generated
+# documentation.
+outputdir   = public
 
-# The headerdirs variable specifies the directories
-# containing the header files associated
-# with the .cpp source files used in the documentation.
+# The headerdirs variable specifies the directories that contain the header
+# files associated with the .cpp source files used in the documentation.
 headerdirs  = .
 
-# The sourcedirs variable specifies the
-# directories containing the .cpp or .qdoc
-# files used in the documentation.
+# The sourcedirs variable specifies the directories that contain the .cpp or
+# .qdoc files used in the documentation.
 sourcedirs  = .
 
-# The exampledirs variable specifies the directories containing
-# the source code of the example files.
-exampledirs = .
+# The exampledirs variable specifies the directories that contain the source
+# code of the example files.
+exampledirs = ./examples
 
-# The imagedirs variable specifies the
-# directories containing the images used in the documentation.
+# The imagedirs variable specifies the directories that contain images used in
+# the documentation.
 imagedirs   = ./images
+
+# Set a warning limit. QDoc will exit with a non-zero exit code if it generates
+# documentation warnings during the documentation build. Useful for tracking
+# down documentation issues.
+#warninglimit = 0
+#warninglimit.enabled = true
diff --git a/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc
index 3c780772c..eb64d6a0d 100644
--- a/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -24,7 +24,7 @@
     define where QDoc should find the various source files, images and
     examples, where to put generated documentation etc. The
     configuration file can also contain directives like \c
-    include. For an example, see \l {minimal-qdocconf}{a minimal qdocconf file}.
+    include. For an example, see \l minimum.qdocconf.
 
     You can also use configuration variables to get QDoc to support
     \l{Supporting Derived Projects} {derived projects}, i.e QDoc can
diff --git a/src/qdoc/qdoc/doc/qdoc-minimum-qdocconf.qdoc b/src/qdoc/qdoc/doc/qdoc-minimum-qdocconf.qdoc
deleted file mode 100644
index f2965db1a..000000000
--- a/src/qdoc/qdoc/doc/qdoc-minimum-qdocconf.qdoc
+++ /dev/null
@@ -1,65 +0,0 @@
-// Copyright (C) 2016 The Qt Company Ltd.
-// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
-/*!
-\page qdoc-minimum-qdocconf.html
-\keyword minimal-qdocconf
-\title A Minimal qdocconf File
-
-\brief Describes a minimal .qdocconf file
-
-Below you will find the full contents of qtgui.qdocconf. The subsequent section
-will discuss every statement in the qdocconf file.
-
-Each line from the qdocconf file is first quoted. Below each statement you will
-find the meaning.
-
-\badcode
-   include(compat.qdocconf)
-   outputdir   = html
-   headerdirs  = .
-   sourcedirs  = .
-   exampledirs = .
-   imagedirs   = ./images
-\endcode
-
-\b Notes:
-
-\badcode
-   include(compat.qdocconf)
-\endcode
-
-For compatibility with older versions of QDoc, it is recommended
-to include compat.qdocconf.
-
-\code
-   outputdir   = html
-\endcode
-
-QDoc will put the documentation generated in the html directory.
-
-\badcode
-   headerdirs  = .
-\endcode
-
-The header file associated with the \e .cpp source files can be found in the
-current directory.
-
-\badcode
-   sourcedirs  = .
-\endcode
-
-The current directory is the directory containing the source files: the \e .cpp
-and \e .qdoc files used in the documentation.
-
-\badcode
-   exampledirs = .
-\endcode
-
-The source code of the example files can be found in the current directory.
-
-\badcode
-   imagedirs   = ./images
-\endcode
-
-The image files can be found in the underlying directory \c images.
-*/