qdoc: Allow per-example override of install path

The 'examplesinstallpath' configuration variable assumes that all
examples - once installed - are located under a common root path.

Add a parameter 'installpath', recognized by the \meta command,
which can be used for setting the install path for specified
examples.

Improve the test for examples-manifest.xml to cover the \meta
command usage.

Task-number: QTBUG-81360
Change-Id: Ibb525a48958005fb3a589ef2d9d212091829231f
Reviewed-by: Levon Sargsyan <levon.sargsyan@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

10 files changed, 85 insertions, 15 deletions

diff --git a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
index 9c11fdd49..51aa3c2cc 100644
--- a/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -3888,6 +3888,22 @@
     This would result in the following tags: \e {tutorial,basic,hello,world}.
     Common words such as \e example are ignored.
 
+    \b {Example Install Paths}
+
+    The \\meta command combined with an argument \c installpath specifies the
+    location of an installed example. This value overrides the one that is set
+    using the \c examplesinstallpath configuration variable.
+
+    \badcode
+    / *!
+        \example helloworld
+        \title Hello World Example
+        \meta {installpath} {tutorials}
+    * /
+    \endcode
+
+    See also \l {examplesinstallpath}.
+
     \target noautolist-command
     \section1 \\noautolist
 
diff --git a/src/qdoc/doc/qtgui-qdocconf.qdoc b/src/qdoc/doc/qtgui-qdocconf.qdoc
index eaed76c67..4161c2917 100644
--- a/src/qdoc/doc/qtgui-qdocconf.qdoc
+++ b/src/qdoc/doc/qtgui-qdocconf.qdoc
@@ -137,7 +137,7 @@ to content listed in the index.
 \note QDoc omits this value when the -installdir argument
 is specified when running QDoc.
 
-\keyword examplesinstallpath
+\target examplesinstallpath
 
 \badcode
    examplesinstallpath     = gui
@@ -150,7 +150,11 @@ installed in the \e gui directory under the parent examples directory
 \note The examplepath variable has to match the example directory specified in
       \c exampledirs.
 
-\b {See also}: \l {exampledirs}.
+\note It is possible to override the \c exampleinstallpath for a specific
+      \l {example-command}{\\example} using the \l {meta-command}{\\meta}
+      command.
+
+\b {See also}: \l {exampledirs} and \l {meta-command}{\\meta}.
 
 \badcode
    qhp.projects    = QtGui
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 846db961a..46d3ad453 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -960,8 +960,10 @@ void Generator::generateLinkToExample(const ExampleNode *en, CodeMarker *marker,
     }
 
     // Construct a path to the example; <install path>/<example name>
-    QStringList path = QStringList()
-            << config()->getString(CONFIG_EXAMPLESINSTALLPATH) << en->name();
+    QString pathRoot = en->doc().metaTagMap().value(QLatin1String("installpath"));
+    if (pathRoot.isEmpty())
+        pathRoot = config()->getString(CONFIG_EXAMPLESINSTALLPATH);
+    QStringList path = QStringList() << pathRoot << en->name();
     path.removeAll({});
 
     Text text;
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index 9f29d099c..8d6d5000f 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -219,8 +219,6 @@ void HtmlGenerator::initializeGenerator(const Config &config)
             + QLatin1Char('/');
     readManifestMetaContent(config);
     examplesPath = config.getString(CONFIG_EXAMPLESINSTALLPATH);
-    if (!examplesPath.isEmpty())
-        examplesPath += QLatin1Char('/');
 
     // Retrieve the config for the navigation bar
     homepage = config.getString(CONFIG_NAVIGATION + Config::dot + CONFIG_HOMEPAGE);
@@ -3892,6 +3890,14 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString
         } else if (en->name().startsWith("demos")) {
             continue;
         }
+
+        // Retrieve the install path specified with \meta command,
+        // or fall back to the one defined in .qdocconf
+        QString installPath = en->doc().metaTagMap().value(QLatin1String("installpath"));
+        if (installPath.isEmpty())
+            installPath = examplesPath;
+        if (!installPath.isEmpty() && !installPath.endsWith(QLatin1Char('/')))
+            installPath += QLatin1Char('/');
         // attributes that are always written for the element
         usedAttributes.clear();
         usedAttributes << "name"
@@ -3911,7 +3917,7 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString
         }
         if (!proFiles.isEmpty()) {
             if (proFiles.size() == 1) {
-                writer.writeAttribute("projectPath", examplesPath + proFiles[0]);
+                writer.writeAttribute("projectPath", installPath + proFiles[0]);
             } else {
                 QString exampleName = en->name().split('/').last();
                 bool proWithExampleNameFound = false;
@@ -3920,13 +3926,13 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString
                         || proFiles[j].endsWith(QStringLiteral("%1/%1.qmlproject").arg(exampleName))
                         || proFiles[j].endsWith(
                                 QStringLiteral("%1/%1.pyproject").arg(exampleName))) {
-                        writer.writeAttribute("projectPath", examplesPath + proFiles[j]);
+                        writer.writeAttribute("projectPath", installPath + proFiles[j]);
                         proWithExampleNameFound = true;
                         break;
                     }
                 }
                 if (!proWithExampleNameFound)
-                    writer.writeAttribute("projectPath", examplesPath + proFiles[0]);
+                    writer.writeAttribute("projectPath", installPath + proFiles[0]);
             }
         }
         if (!en->imageFileName().isEmpty()) {
@@ -4064,7 +4070,7 @@ void HtmlGenerator::generateManifestFile(const QString &manifest, const QString
             if (--it == filesToOpen.constBegin()) {
                 writer.writeAttribute(QStringLiteral("mainFile"), QStringLiteral("true"));
             }
-            writer.writeCharacters(examplesPath + it.value());
+            writer.writeCharacters(installPath + it.value());
             writer.writeEndElement();
         }
 
diff --git a/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf b/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf
index 816d1d1a4..b4598476e 100644
--- a/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf
+++ b/tests/auto/qdoc/generatedoutput/examples-qhp.qdocconf
@@ -1,6 +1,8 @@
 # QML test includes a documented example
 include(testqml.qdocconf)
 
+examplesinstallpath = test
+
 # Configure .qhp generation
 qhp.projects            = Test
 
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml b/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml
index 330923033..7f206d0e8 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/examples-manifest.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <instructionals module="Test">
     <examples>
-        <example name="QML Documentation Example" docUrl="qthelp://org.qt-project.test.001/test/test-componentset-example.html" isTest="true">
-            <description><![CDATA[No description available]]></description>
-            <tags>documentation,qml,test</tags>
+        <example name="QML Documentation Example" docUrl="qthelp://org.qt-project.test.001/test/test-componentset-example.html" projectPath="tutorials/componentset/componentset.pro" isTest="true">
+            <description><![CDATA[Example for documenting QML types.]]></description>
+            <tags>documentation,qml,sample,test</tags>
         </example>
     </examples>
 </instructionals>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml
index 8689d2e76..29ed944ba 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/html/test-componentset-example.webxml
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <WebXML>
     <document>
-        <page name="componentset" href="test-componentset-example.html" status="active" location="examples.qdoc" filepath="/home/levon/work/official/qttools/tests/auto/qdoc/generatedoutput/examples.qdoc" lineno="28" documented="true" subtype="example" title="QML Documentation Example" fulltitle="QML Documentation Example" subtitle="" module="Test">
+        <page name="componentset" href="test-componentset-example.html" status="active" location="examples.qdoc" filepath="/home/levon/work/official/qttools/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc" lineno="28" documented="true" subtype="example" title="QML Documentation Example" fulltitle="QML Documentation Example" subtitle="" module="Test" brief="Example for documenting QML types">
             <contents name="qml-class" title="QML Class" level="1"/>
             <contents name="properties-signals-handlers-and-methods" title="Properties, Signals, Handlers, and Methods" level="1"/>
             <contents name="internal-documentation" title="Internal Documentation" level="2"/>
             <contents name="qml-types-with-c-implementation" title="QML Types with C++ Implementation" level="1"/>
-            <description path="/home/levon/work/official/qttools/tests/auto/qdoc/generatedoutput/examples.qdoc" line="28" column="4">
+            <description path="/home/levon/work/official/qttools/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc" line="28" column="4">
+                <brief>Example for documenting QML types.</brief>
                 <para>This example demonstrates one of the ways to document QML types.</para>
                 <para>In particular, there are sample types that are documented with QDoc commands comments. There are documentation comments for the QML types and their public interfaces. The types are grouped into a module, the <link raw="UI Components" href="uicomponents-qmlmodule.html" type="">UI Components</link> module.</para>
                 <para>The uicomponents.qdoc file generates the overview page for the <link raw="UI Components" href="uicomponents-qmlmodule.html" type="">UI Components</link> module page.</para>
@@ -32,6 +33,29 @@ An aliased property of type int.</code>
                     <heading level="1">QML Types with C++ Implementation</heading>
                     <para>This example only demonstrates the documentation for types in QML files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type.</para>
                 </section>
+                <para>Files:</para>
+                <list type="bullet">
+                    <item>
+                        <para>
+                            <link raw="componentset/ProgressBar.qml" href="test-componentset-progressbar-qml.html" type="page" page="ProgressBar.qml Example File">componentset/ProgressBar.qml</link>
+                        </para>
+                    </item>
+                    <item>
+                        <para>
+                            <link raw="componentset/Switch.qml" href="test-componentset-switch-qml.html" type="page" page="Switch.qml Example File">componentset/Switch.qml</link>
+                        </para>
+                    </item>
+                    <item>
+                        <para>
+                            <link raw="componentset/TabWidget.qml" href="test-componentset-tabwidget-qml.html" type="page" page="TabWidget.qml Example File">componentset/TabWidget.qml</link>
+                        </para>
+                    </item>
+                    <item>
+                        <para>
+                            <link raw="componentset/componentset.pro" href="test-componentset-componentset-pro.html" type="page" page="componentset.pro Example File">componentset/componentset.pro</link>
+                        </para>
+                    </item>
+                </list>
             </description>
         </page>
     </document>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html b/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html
index faf632bea..8b792090f 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/test-componentset-example.html
@@ -19,6 +19,9 @@
 <div class="sidebar-content" id="sidebar-content"></div></div>
 <h1 class="title">QML Documentation Example</h1>
 <span class="subtitle"></span>
+<!-- $$$componentset-brief -->
+<p>Example for documenting QML types.</p>
+<!-- @@@componentset -->
 <!-- $$$componentset-description -->
 <div class="descr"> <a name="details"></a>
 <p>This example demonstrates one of the ways to document QML types.</p>
@@ -42,6 +45,13 @@ An aliased property of type <span class="type">int</span><span class="operator">
 <a name="qml-types-with-c-implementation"></a>
 <h4 id="qml-types-with-c-implementation">QML Types with C++ Implementation</h4>
 <p>This example only demonstrates the documentation for types in QML files, but the regular QML commands may be placed inside C++ classes to define the public API of the QML type.</p>
+<p>Files:</p>
+<ul>
+<li><a href="test-componentset-progressbar-qml.html">componentset/ProgressBar.qml</a></li>
+<li><a href="test-componentset-switch-qml.html">componentset/Switch.qml</a></li>
+<li><a href="test-componentset-tabwidget-qml.html">componentset/TabWidget.qml</a></li>
+<li><a href="test-componentset-componentset-pro.html">componentset/componentset.pro</a></li>
+</ul>
 </div>
 <!-- @@@componentset -->
 </body>
diff --git a/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc b/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc
index 7c780eca8..2f56c221c 100644
--- a/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc
+++ b/tests/auto/qdoc/generatedoutput/qml/componentset/examples.qdoc
@@ -28,6 +28,10 @@
 /*!
     \example componentset
     \title QML Documentation Example
+    \brief Example for documenting QML types.
+
+    \meta tag {test,sample}
+    \meta installpath tutorials
 
     This example demonstrates one of the ways to document QML types.
 
diff --git a/tests/auto/qdoc/generatedoutput/testqml.qdocconf b/tests/auto/qdoc/generatedoutput/testqml.qdocconf
index c469bde06..f618fe1b8 100644
--- a/tests/auto/qdoc/generatedoutput/testqml.qdocconf
+++ b/tests/auto/qdoc/generatedoutput/testqml.qdocconf
@@ -16,5 +16,7 @@ excludedirs = ./bug80259
 sources.fileextensions = "*.qml *.cpp *.qdoc"
 headers.fileextensions = "*.h"
 
+examples.fileextensions = "*.qml"
+
 macro.begincomment      = "\\c{/*}"
 macro.QDocTestVer       = "1.1"