qdoc: Allow replacing file lists on \example pages with a link to a URLv5.13.0-beta2

Source and image file lists that are automatically generated at the end
of example pages have outlived their usefulness, at least for Qt docs.
When browsing example documentation offline via Qt Creator's Help, the
user has typically already opened the example project. For online
documentation, a better option is to link to a remote repository where
the user can browse the example's content.

This commit adds a new configuration variable 'url.examples' - if
defined, file listings are omitted and a link is constructed for each
example based on the parameter passed to the \example command and
the 'examplesinstallpath' configuration variable.

Task-number: QTBUG-74391
Change-Id: If1f76ee34c5e50236fae626f251e00bf24c1045d
Reviewed-by: Martin Smith <martin.smith@qt.io>

4 files changed, 114 insertions, 10 deletions

diff --git a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
index 0080c6a99..0f38aabce 100644
--- a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -121,6 +121,8 @@
     \li \l {sources.fileextensions-variable} {sources.fileextensions}
     \li \l {spurious-variable} {spurious}
     \li \l {tabsize-variable} {tabsize}
+    \li \l {url-variable} {url}
+    \li \l {url.examples-variable} {url.examples}
     \li \l {version-variable} {version}
     \li \l {versionsym-variable} {versionsym}
     \li \l {warninglimit-variable} {warninglimit}
@@ -1699,7 +1701,59 @@
     references to for example Qt classes, the base URL is \c
     http://doc.qt.io/qt-4.8/.
 
-    See also \l indexes.
+    See also \l indexes and \l {url.examples}.
+
+    \target url.examples-variable
+    \section1 url.examples
+
+    The \c url.examples variable holds the base URL for the examples
+    associated with the current project.
+
+    If defined, a link to the example project directory is generated
+    at the end of each example documentation page. The \c url.examples
+    variable refers to the root directory of the examples related to
+    this project; it can be a link to an online repository (starting
+    with \e http:// or \e https://), or to the local file system
+    (\c file://).
+
+    If \c url.examples is not defined, QDoc will output a list of
+    example's files and images instead.
+
+    For example, given these definitions:
+
+    \badcode
+    url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
+    examplesinstallpath = corelib
+    \endcode
+
+    Then, for the following \l {example-command}{\\example} command:
+
+    \badcode *
+    /\1!
+        \example threads/semaphores
+        ...
+    \1/
+    \endcode
+
+    QDoc generates a link to
+    \c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores.
+
+    If the URL contains more components (for example, a query string)
+    after the example path, \\1 can be used as a placeholder for the
+    path:
+
+    \badcode
+    url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
+    examplesinstallpath = corelib
+    \endcode
+
+    Given the same \\example command as above and assuming that
+    \c $QT_VER expands to \c {5.13}, the generated URL is
+    \c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13.
+
+    \c {url.examples} variable was introduced in QDoc version 5.13.
+
+    See also \l url, \l examplesinstallpath, and \l {example-command}{\\example}.
 
     \target howto
     \section1 How to Support Derived Projects
diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
index 05e7b331b..4e80f8f12 100644
--- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -366,7 +366,9 @@
 
     The documentation page will be output to \c {modulename-path-to-example}.html.
     QDoc will add a list of all the example's source and images files at the end
-    of the page, unless \l {noautolist-command}{\\noautolist} command is used.
+    of the page, unless \l {noautolist-command}{\\noautolist} command is used or
+    the configuration variable \l {url.examples-variable}{url.examples} is defined
+    for the project.
 
     For example, if \l {exampledirs-variable} {exampledirs} contains
     \c $QTDIR/examples/widgets/imageviewer, then
@@ -410,6 +412,7 @@
 
     \b {See also:} \l {generatelist-command}{\\generatelist examplefiles},
                    \l {noautolist-command}{\\noautolist},
+                   \l {url.examples-variable}{url.examples},
                    \l {meta-command}{\\meta}
 
     \target externalpage-command
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index e5720d5fb..ac5ee56ef 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -42,6 +42,9 @@
 #include "separator.h"
 #include "tokenizer.h"
 #include "qdocdatabase.h"
+#ifndef QT_BOOTSTRAPPED
+#  include "QtCore/qurl.h"
+#endif
 
 QT_BEGIN_NAMESPACE
 
@@ -935,9 +938,14 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
         }
     }
 
+    // For examples, generate either a link to the project directory
+    // (if url.examples is defined), or a list of files/images.
     if (node->isExample()) {
         const ExampleNode* en = static_cast<const ExampleNode*>(node);
-        if (!en->noAutoList()) {
+        QString exampleUrl = config()->getString(CONFIG_URL + Config::dot + CONFIG_EXAMPLES);
+        if (!exampleUrl.isEmpty()) {
+            generateLinkToExample(en, marker, exampleUrl);
+        } else if (!en->noAutoList()) {
             generateFileList(en, marker, false);
             generateFileList(en, marker, true);
         }
@@ -945,6 +953,49 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
 }
 
 /*!
+  Generates a link to the project folder for example node \a en.
+  \a baseUrl is the base URL - path information is available in
+  the example node's name() and 'examplesinstallpath' configuration
+  variable.
+*/
+void Generator::generateLinkToExample(const ExampleNode *en,
+                                      CodeMarker *marker,
+                                      const QString &baseUrl)
+{
+        Text text;
+        QString exampleUrl(baseUrl);
+
+        if (!exampleUrl.contains("\1")) {
+            if (!exampleUrl.endsWith("/"))
+                exampleUrl += "/";
+            exampleUrl += "\1";
+        }
+
+        // Name of the example node is the path, relative to install path
+        QStringList path = QStringList()
+            << config()->getString(CONFIG_EXAMPLESINSTALLPATH)
+            << en->name();
+        path.removeAll({});
+
+        QString link;
+#ifndef QT_BOOTSTRAPPED
+        link = QUrl(baseUrl).host();
+#endif
+        if (!link.isEmpty())
+            link.prepend(" @ ");
+        link.prepend("Example project");
+
+        text << Atom::ParaLeft
+             << Atom(Atom::Link, exampleUrl.replace("\1", path.join("/")))
+             << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
+             << Atom(Atom::String, link)
+             << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
+             << Atom::ParaRight;
+
+        generateText(text, 0, marker);
+}
+
+/*!
   This function is called when the documentation for an example is
   being formatted. It outputs a list of files for the example, which
   can be the example's source files or the list of images used by the
diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h
index 91ba1d98e..d02c59f44 100644
--- a/src/qdoc/generator.h
+++ b/src/qdoc/generator.h
@@ -156,14 +156,10 @@ protected:
                                  CodeMarker *marker,
                                  bool generate,
                                  int& numGeneratedAtoms);
+    void generateLinkToExample(const ExampleNode *en,
+                               CodeMarker *marker,
+                               const QString &baseUrl);
     void generateFileList(const ExampleNode* en, CodeMarker* marker, bool images);
-#if 0
-    // Keeping this until usage shows we no longer need it. mws 17/08/2018
-    void generateFileList(const PageNode* pn,
-                          CodeMarker* marker,
-                          Node::NodeSubtype subtype,
-                          const QString& regExp);
-#endif
     void generateSince(const Node *node, CodeMarker *marker);
     void generateStatus(const Node *node, CodeMarker *marker);
     void generatePrivateSignalNote(const Node* node, CodeMarker* marker);