qdoc: Enable correct linking to externally-built dependencies

So far, there were two types of modular documentation build scenarios
that QDoc supported:

 - All modules are part of the same build, installed to a location with
   known structure. Cross-linking done via relative references:
   <a href="../qtcore/qstring.html">, or

 - All dependencies (.index files) are treated as external documentation
   modules, cross-linking done via full URLs:
   <a href="https://doc.qt.io/qt/qstring.html">.

Enable a mix of these two: that is, a modular build of documentation
(e.g. qt5) with local cross-linking, optionally with addon .index files
pulled into the build. Linking to these external dependencies are done
with full URLs.

QDoc now uses the 'url' configuration variable, recorded in the .index,
to determine whether a dependency is part of the same high-level
project as the one loading the .index file. For example, all
documentation projects in qt5's submodules use a common configuration
that sets a URL, https://doc.qt.io/qt, for all of them.

[ChangeLog][QDoc][QDoc now allows loading external .index files into a
modular documentation build, with correct linking.]

Pick-to: 6.2 6.4
Fixes: QTBUG-107762
Change-Id: Ib6dfb6b76be049f813541be896365b175b224feb
Reviewed-by: Luca Di Sera <luca.disera@qt.io>

5 files changed, 24 insertions, 18 deletions

diff --git a/src/qdoc/qdocindexfiles.cpp b/src/qdoc/qdocindexfiles.cpp
index ce4039eda..1ac610238 100644
--- a/src/qdoc/qdocindexfiles.cpp
+++ b/src/qdoc/qdocindexfiles.cpp
@@ -122,15 +122,16 @@ void QDocIndexFiles::readIndexFile(const QString &path)
 
     QXmlStreamAttributes attrs = reader.attributes();
 
-    // Generate a relative URL between the install dir and the index file
-    // when the -installdir command line option is set.
-    QString indexUrl;
-    if (Config::installDir.isEmpty()) {
-        indexUrl = attrs.value(QLatin1String("url")).toString();
-    } else {
-        // Use a fake directory, since we will copy the output to a sub directory of
-        // installDir when using "make install". This is just for a proper relative path.
-        // QDir installDir(path.section('/', 0, -3) + "/outputdir");
+    QString indexUrl {attrs.value(QLatin1String("url")).toString()};
+
+    // Decide how we link to nodes loaded from this index file:
+    // If building a set that will be installed AND the URL of
+    // the dependency is identical to ours, assume that also
+    // the dependent html files are available under the same
+    // directory tree. Otherwise, link using the full index URL.
+    if (!Config::installDir.isEmpty() && indexUrl == Config::instance().getString(CONFIG_URL)) {
+        // Generate a relative URL between the install dir and the index file
+        // when the -installdir command line option is set.
         QDir installDir(path.section('/', 0, -3) + '/' + Generator::outputSubdir());
         indexUrl = installDir.relativeFilePath(path).section('/', 0, -2);
     }
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/index-linking.html b/tests/auto/qdoc/generatedoutput/expected_output/index-linking.html
index 600d6d4e6..89d59dfc9 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/index-linking.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/index-linking.html
@@ -18,8 +18,8 @@
 <!-- $$$index-linking.html-description -->
 <div class="descr" id="details">
 <h2 id="qml-properties">QML properties</h2>
-<ol class="A" type="A"><li>Property group: <a href="qml-qdoc-test-parent.html#group-prop">Parent::group</a>.</li>
-<li>Property in a group: <a href="qml-qdoc-test-parent.html#group.c-prop">QDoc.Test::Parent::group.c</a>.</li>
+<ol class="A" type="A"><li>Property group: <a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html#group-prop">Parent::group</a>.</li>
+<li>Property in a group: <a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html#group.c-prop">QDoc.Test::Parent::group.c</a>.</li>
 </ol>
 </div>
 <!-- @@@index-linking.html -->
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qml-linkmodule-grandchild-members.html b/tests/auto/qdoc/generatedoutput/expected_output/qml-linkmodule-grandchild-members.html
index 3527f5c71..eb7cc77ee 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qml-linkmodule-grandchild-members.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qml-linkmodule-grandchild-members.html
@@ -11,16 +11,16 @@
 <div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
 <h1 class="title">List of All Members for GrandChild</h1>
 <p>This is the complete list of members for <a href="qml-linkmodule-grandchild.html">GrandChild</a>, including inherited members.</p>
-<p>The following members are inherited from <a href="qml-qdoc-test-anotherchild.html">AnotherChild</a>.</p>
+<p>The following members are inherited from <a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-anotherchild.html">AnotherChild</a>.</p>
 <ul>
-<li class="fn"><b><a href="qml-qdoc-test-anotherchild.html#name-prop">name</a></b> : string</li>
+<li class="fn"><b><a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-anotherchild.html#name-prop">name</a></b> : string</li>
 </ul>
-<p>The following members are inherited from <a href="qml-qdoc-test-parent.html">Parent</a>.</p>
+<p>The following members are inherited from <a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html">Parent</a>.</p>
 <ul>
-<li class="fn"><b><a href="qml-qdoc-test-parent.html#group-prop">group</a></b> : </li>
-<li class="fn"><b><a href="qml-qdoc-test-parent.html#group.a-prop">group.a</a></b> : int</li>
-<li class="fn"><b><a href="qml-qdoc-test-parent.html#group.b-prop">group.b</a></b> : int</li>
-<li class="fn"><b><a href="qml-qdoc-test-parent.html#group.c-prop">group.c</a></b> : int</li>
+<li class="fn"><b><a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html#group-prop">group</a></b> : </li>
+<li class="fn"><b><a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html#group.a-prop">group.a</a></b> : int</li>
+<li class="fn"><b><a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html#group.b-prop">group.b</a></b> : int</li>
+<li class="fn"><b><a href="https://doc.qt.io/QmlPropertyGroups/qml-qdoc-test-parent.html#group.c-prop">group.c</a></b> : int</li>
 </ul>
 </body>
 </html>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/indexlinking/indexlinking.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/indexlinking/indexlinking.qdocconf
index 4f5fe22b0..55dfa6985 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/indexlinking/indexlinking.qdocconf
+++ b/tests/auto/qdoc/generatedoutput/testdata/indexlinking/indexlinking.qdocconf
@@ -1,6 +1,10 @@
 # test linking to entities loaded from index
 project = IndexLinking
 
+# Use a URL different from what the dependency below uses,
+# to avoid linking with relative paths. See QTBUG-107762.
+url = indexlinking
+
 depends = \
     qmlpropertygroups
 
diff --git a/tests/auto/qdoc/generatedoutput/testdata/qmlpropertygroups/qmlpropertygroups.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/qmlpropertygroups/qmlpropertygroups.qdocconf
index 1f876d030..53fecd995 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/qmlpropertygroups/qmlpropertygroups.qdocconf
+++ b/tests/auto/qdoc/generatedoutput/testdata/qmlpropertygroups/qmlpropertygroups.qdocconf
@@ -1,6 +1,7 @@
 include(../configs/testqml.qdocconf)
 
 project = QmlPropertyGroups
+url = https://doc.qt.io/${project}
 
 sourcedirs += .