qdoc: Introduce automatic generation of navigation links

Introduce a new configuration variable, navigation.toctitles, for
automatic generation of navigation links for pages listed in a TOC.

A TOC page is a \page with a \list, where list elements define the pages
included in the documentation set. When set, QDoc will generate links
for these pages, without the need for \nextpage and \previouspage
commands.

[ChangeLog][qdoc] Added a capability to generate navigation links for
pages listed in a TOC.

Fixes: QTBUG-84238
Change-Id: I0b34d8a0fe4b01a2ffcc084e6416c0a4b4623b78
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

11 files changed, 96 insertions, 4 deletions

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-linking.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-linking.xml
index 7909b62f2..90c76d8ee 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-linking.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-linking.xml
@@ -5,7 +5,7 @@
 <db:productname>OutputFromQDocFiles</db:productname>
 <db:edition>OutputFromQDocFiles - A test project for QDoc build artifacts</db:edition>
 <db:titleabbrev>A test project for QDoc build artifacts</db:titleabbrev>
-<db:abstract>
+<db:extendedlink><db:link xlink:to="qdoctests-qdocfileoutput.xml" xlink:title="prev" xlink:label="QDoc Testing"/></db:extendedlink><db:extendedlink><db:link xlink:to="toc.xml" xlink:title="prev" xlink:label="Table of Contents"/></db:extendedlink><db:abstract>
 <db:para>This is a page for testing QDoc's link command.</db:para>
 </db:abstract>
 </db:info>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml
index f5f27c310..1e230d3b7 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml
@@ -5,7 +5,7 @@
 <db:productname>OutputFromQDocFiles</db:productname>
 <db:edition>OutputFromQDocFiles - A test project for QDoc build artifacts</db:edition>
 <db:titleabbrev>A test project for QDoc build artifacts</db:titleabbrev>
-<db:abstract>
+<db:extendedlink><db:link xlink:to="qdoctests-qdocfileoutput-linking.xml" xlink:title="prev" xlink:label="QDoc Linking Test"/></db:extendedlink><db:abstract>
 <db:para>This is a simple page for testing purposes only.</db:para>
 </db:abstract>
 </db:info>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput-linking.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput-linking.webxml
index 3983c2bbd..b3ad4ee3b 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput-linking.webxml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput-linking.webxml
@@ -6,6 +6,8 @@
             <keyword name="qdoc-linking-test" title="QDoc Linking Test"/>
             <contents name="link-targets" title="Link targets" level="1"/>
             <description>
+                <relation href="toc.html" type="page" meta="next" description="Table of Contents"/>
+                <relation href="qdoctests-qdocfileoutput.html" type="page" meta="previous" description="Testing QDoc output from .qdoc files"/>
                 <brief>This is a page for testing QDoc's link command.</brief>
                 <target name="link-test-target"/>
                 <section id="link-targets">
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml
index 4a56533a4..2d9c786d8 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml
+++ b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml
@@ -6,6 +6,7 @@
             <contents name="further-information" title="Further information" level="1"/>
             <contents name="linking" title="Linking" level="1"/>
             <description>
+                <relation href="qdoctests-qdocfileoutput-linking.html" type="page" meta="next" description="Testing QDoc's link command"/>
                 <brief>This is a simple page for testing purposes only.</brief>
                 <para>QDoc generates documentation for software projects. It does this by extracting <italic>QDoc comments</italic> from project source files. QDoc comments are signified by a C-style-like comment tag followed by an exclamation point, like this: <teletype type="highlighted">/*!</teletype> <teletype type="highlighted">This text is contained within QDoc comment tags.</teletype> <teletype type="highlighted">*/</teletype>.</para>
                 <section id="supported-file-types">
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-linking.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-linking.html
index 189d2275f..4da717b70 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-linking.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-linking.html
@@ -7,6 +7,12 @@
 </head>
 <body>
 <li id="buildversion">OutputFromQDocFiles - A test project for QDoc build artifacts</li>
+  <link rel="prev" href="qdoctests-qdocfileoutput.html" />
+  <link rel="next" href="toc.html" />
+<p class="naviNextPrevious headerNavi">
+<a class="prevPage" href="qdoctests-qdocfileoutput.html">QDoc Testing</a>
+<a class="nextPage" href="toc.html">Table of Contents</a>
+</p><p/>
 <div class="sidebar">
 <div class="toc">
 <h3><a name="toc">Contents</a></h3>
@@ -24,5 +30,9 @@
 <p>Valid parameters for the link command (<code>\l</code>) are page and section titles, targets defined with \target or \keyword commands, and API reference keywords (types, methods, namespaces, and so on).</p>
 </div>
 <!-- @@@qdoctests-qdocfileoutput-linking.html -->
+<p class="naviNextPrevious footerNavi">
+<a class="prevPage" href="qdoctests-qdocfileoutput.html">QDoc Testing</a>
+<a class="nextPage" href="toc.html">Table of Contents</a>
+</p>
 </body>
 </html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html
index 9c52a9808..273b0110e 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html
@@ -7,6 +7,10 @@
 </head>
 <body>
 <li id="buildversion">OutputFromQDocFiles - A test project for QDoc build artifacts</li>
+  <link rel="next" href="qdoctests-qdocfileoutput-linking.html" />
+<p class="naviNextPrevious headerNavi">
+<a class="nextPage" href="qdoctests-qdocfileoutput-linking.html">QDoc Linking Test</a>
+</p><p/>
 <div class="sidebar">
 <div class="toc">
 <h3><a name="toc">Contents</a></h3>
@@ -50,5 +54,8 @@
 </ul>
 </div>
 <!-- @@@qdoctests-qdocfileoutput.html -->
+<p class="naviNextPrevious footerNavi">
+<a class="nextPage" href="qdoctests-qdocfileoutput-linking.html">QDoc Linking Test</a>
+</p>
 </body>
 </html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/toc.html b/tests/auto/qdoc/generatedoutput/expected_output/toc.html
new file mode 100644
index 000000000..cd4a50328
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/toc.html
@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- qdoctests-outputfromqdocfiles.qdoc -->
+  <title>Table of Contents | OutputFromQDocFiles</title>
+</head>
+<body>
+<li id="buildversion">OutputFromQDocFiles - A test project for QDoc build artifacts</li>
+  <link rel="prev" href="qdoctests-qdocfileoutput-linking.html" />
+<p class="naviNextPrevious headerNavi">
+<a class="prevPage" href="qdoctests-qdocfileoutput-linking.html">QDoc Linking Test</a>
+</p><p/>
+<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title">Table of Contents</h1>
+<span class="subtitle"></span>
+<!-- $$$toc.html-description -->
+<div class="descr"> <a name="details"></a>
+<ul>
+<li><a href="qdoctests-qdocfileoutput.html">QDoc Testing</a></li>
+<li><a href="qdoctests-qdocfileoutput-linking.html">QDoc Linking Test</a></li>
+<li><a href="toc.html">Table of Contents</a></li>
+</ul>
+</div>
+<!-- @@@toc.html -->
+<p class="naviNextPrevious footerNavi">
+<a class="prevPage" href="qdoctests-qdocfileoutput-linking.html">QDoc Linking Test</a>
+</p>
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf
index f1ab7ec2e..bcc5c0926 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf
+++ b/tests/auto/qdoc/generatedoutput/testdata/configs/test.qdocconf
@@ -7,6 +7,9 @@ sources = ../outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
 
 macro.beginqdoc = "\\c {/*!}"
 macro.endqdoc = "\\c */"
+macro.PROD = QDoc
+
+defines = test_navigation
 
 # zero warning tolerance
 warninglimit = 0
diff --git a/tests/auto/qdoc/generatedoutput/testdata/configs/tocnavigation.qdocconf b/tests/auto/qdoc/generatedoutput/testdata/configs/tocnavigation.qdocconf
new file mode 100644
index 000000000..69e0dfac2
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/testdata/configs/tocnavigation.qdocconf
@@ -0,0 +1,4 @@
+include(test.qdocconf)
+
+defines =
+navigation.toctitles = "Table of Contents"
diff --git a/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc b/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
index e56c447c4..36d85fb35 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
+++ b/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc
@@ -26,8 +26,12 @@
 ****************************************************************************/
 
 /*!
+\if defined(test_navigation)
+    \nextpage {qdoctests-qdocfileoutput-linking.html}{QDoc Linking Test}
+\endif
+
     \page qdoctests-qdocfileoutput.html
-    \title Testing QDoc output from .qdoc files
+    \title Testing \PROD output from .qdoc files
     \brief This is a simple page for testing purposes only.
 
     QDoc generates documentation for software projects. It does this by
@@ -69,6 +73,11 @@
 */
 
 /*!
+\if defined(test_navigation)
+    \previouspage qdoctests-qdocfileoutput.html \PROD Testing
+    \nextpage Table of Contents
+\endif
+
     \keyword QDoc Linking Test
     \page qdoctests-qdocfileoutput-linking.html
     \title Testing QDoc's link command
@@ -81,3 +90,18 @@
     titles, targets defined with \\target or \\keyword commands, and API
     reference keywords (types, methods, namespaces, and so on).
 */
+
+/*!
+\if defined(test_navigation)
+    \previouspage {Testing QDoc's link command}{QDoc Linking Test}
+\endif
+
+    \page toc.html
+    \title Table of Contents
+
+    \list
+        \li \l {Testing \PROD output from .qdoc files}{\PROD Testing}
+        \li \l {QDoc Linking Test}
+        \li \l {Table of Contents}
+    \endlist
+*/
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 42cb2570c..963a8559e 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -56,6 +56,7 @@ private slots:
     void docBookFromQml();
 
     // Output format independent tests
+    void autoNavigation();
     void examplesManifestXmlAndQhp();
     void ignoresinceVariable();
     void templateParameters();
@@ -190,7 +191,8 @@ void tst_generatedOutput::htmlFromQDocFile()
 {
     testAndCompare("testdata/configs/test.qdocconf",
                    "qdoctests-qdocfileoutput.html "
-                   "qdoctests-qdocfileoutput-linking.html");
+                   "qdoctests-qdocfileoutput-linking.html "
+                   "toc.html");
 }
 
 void tst_generatedOutput::htmlFromCpp()
@@ -292,6 +294,15 @@ void tst_generatedOutput::docBookFromQml()
                    "docbook/qml-int.xml");
 }
 
+void tst_generatedOutput::autoNavigation()
+{
+    // Same expected files as htmlFromQdocFile, but with auto-generated navigation links
+    testAndCompare("testdata/configs/tocnavigation.qdocconf",
+                   "qdoctests-qdocfileoutput.html "
+                   "qdoctests-qdocfileoutput-linking.html "
+                   "toc.html");
+}
+
 void tst_generatedOutput::examplesManifestXmlAndQhp()
 {
     testAndCompare("testdata/configs/examples-qhp.qdocconf",