From 92a2ae28aa2c97053c912d432cb8e62e8c59e383 Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Thu, 14 Jul 2022 11:22:09 +0200
Subject: Doc: QDoc Manual: Document the examplesinstallpath qdocconf variable

This variable was briefly mentioned in the breakdown of a sample
.qdocconf file but not properly documented. Add a section for it
in the list of variables.

Clean up the sample .qdocconf file in passing.

Fixes: QTBUG-104633
Change-Id: Icf8ee395f1add63e6382e1f0c715b22f4f3bc7c6
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 32be6fc6e8d7e66dca2c70359647cc7f0c917210)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 src/qdoc/doc/qdoc-manual-qdocconf.qdoc | 53 ++++++++++++++++++++++++++++++++++
 src/qdoc/doc/qtgui-qdocconf.qdoc       | 17 +++++------
 2 files changed, 61 insertions(+), 9 deletions(-)

diff --git a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
index f1f15e110..8be23cd48 100644
--- a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -147,6 +147,7 @@
     \li \l {depends-variable} {depends}
     \li \l {exampledirs-variable} {exampledirs}
     \li \l {examples-variable} {examples}
+    \li \l {examplesinstallpath-variable} {examplesinstallpath}
     \li \l {examples.fileextensions-variable} {examples.fileextensions}
     \li \l {excludedirs-variable} {excludedirs}
     \li \l {excludefiles-variable} {excludefiles}
@@ -442,6 +443,58 @@
 
     See also \l {exampledirs-variable} {exampledirs}.
 
+    \target examplesinstallpath-variable
+    \section1 examplesinstallpath
+
+    The \c examplesinstallpath variable sets the root path for this
+    project's examples under the \e installed example directory.
+
+    Assuming a root install path of \c QT_INSTALL_EXAMPLES for all
+    examples, then the path
+
+    \badcode
+    <QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>
+    \endcode
+
+    will be used to refer to a path of a single example within this
+    documentation project. These paths are recorded in the
+    \l {Example Manifest Files} {example manifest file}, read by Qt
+    Creator.
+
+    To ensure correct paths, \c examplesinstallpath must match with
+    one of the directories listed in \l {exampledirs-variable}
+    {exampledirs}. The path passed as an argument for each
+    \l {example-command} {\\example} command is relative to
+    the path in \e exampledirs.
+
+    For example:
+
+    \badcode
+    exampledirs = ./snippets \
+                  ../../../examples/mymodule
+
+    examplesinstallpath = mymodule
+    \endcode
+
+    And given a following \\example command:
+
+    \badcode *
+    /*!
+        \example basic/hello
+        ...
+    \1/
+    \endcode
+
+    Then, the path \c {mymodule/basic/hello} is recorded in the manifest file
+    for this example.
+
+    \note It is possible to override \c examplesinstallpath for an individual
+          \l {example-command}{\\example} using the \l {meta-command}{\\meta}
+          command.
+
+    \b {See also}: \l {exampledirs}, \l {example-command} {\\example}, and
+    \l {meta-command}{\\meta}.
+
     \target examples.fileextensions-variable
     \section1 examples.fileextensions
 
diff --git a/src/qdoc/doc/qtgui-qdocconf.qdoc b/src/qdoc/doc/qtgui-qdocconf.qdoc
index 48aaff5b6..b72f97271 100644
--- a/src/qdoc/doc/qtgui-qdocconf.qdoc
+++ b/src/qdoc/doc/qtgui-qdocconf.qdoc
@@ -19,7 +19,7 @@ every statement in the qdocconf file.
 
    project                 = QtGui
    description             = Qt GUI Reference Documentation
-   url                     = http://doc.qt.io/qt-5
+   url                     = http://doc.qt.io/qt
    version                 = $QT_VERSION
 
    examplesinstallpath     = gui
@@ -35,10 +35,10 @@ every statement in the qdocconf file.
    qhp.QtGui.subprojects         = classes
    qhp.QtGui.subprojects.classes.title = C++ Classes
    qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
-   qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
+   qhp.QtGui.subprojects.classes.selectors = class headerfile
    qhp.QtGui.subprojects.classes.sortPages = true
 
-   tagfile                 = ../../../doc/qtgui/qtgui.tags
+   tagfile                 = qtgui.tags
 
    depends += \
        qtcore \
@@ -62,7 +62,7 @@ every statement in the qdocconf file.
 
    imagedirs   += images \
                   ../../../examples/gui/doc/images \
-                  ../../../doc/src/images \
+                  ../../../doc/src/images
 \endcode
 
 \title Qtgui.qdocconf with notes
@@ -109,24 +109,23 @@ to content listed in the index.
 \note QDoc omits this value when the -installdir argument
 is specified when running QDoc.
 
-\target examplesinstallpath
-
 \badcode
    examplesinstallpath     = gui
 \endcode
 
-This \c examplesinstallpath variable indicates that the examples will be
+The \c examplesinstallpath variable indicates that the examples will be
 installed in the \e gui directory under the parent examples directory
 (for Qt, this is $QT_INSTALL_EXAMPLES).
 
 \note The examplepath variable has to match the example directory specified in
       \c exampledirs.
 
-\note It is possible to override the \c exampleinstallpath for a specific
+\note It is possible to override \c examplesinstallpath for a specific
       \l {example-command}{\\example} using the \l {meta-command}{\\meta}
       command.
 
-\b {See also}: \l {exampledirs} and \l {meta-command}{\\meta}.
+\b {See also}: \l {examplesinstallpath}, \l {exampledirs}, and
+\l {meta-command}{\\meta}.
 
 \badcode
    qhp.projects    = QtGui
-- 
cgit v1.2.3