qdoc: WebXML output format: Fix issues with example pages

Since QDoc no longer stores example files as nodes in its tree, the
WebXMLGenerator failed to generate output for those files.

Fix this by generating those pages explicitly as needed, overriding
functions from the Generator base class.

Prevent QDocIndexFiles from writing nested <page> elements when
WebXMLGenerator is in use, as that does not work as expected with
shiboken2.

Fixes: PYSIDE-1088
Change-Id: I01c2af2391726f448271fdb810ffc3da923caca5
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 81 insertions, 44 deletions

diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index de9976502..d5caa8bd0 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -447,9 +447,13 @@ QString Generator::fileBase(const Node *node) const
 
 /*!
   Constructs an href link from an example file name, which
-  is a path to the example file.
+  is a path to the example file. If \a fileExtension is
+  empty (default value), retrieve the file extension from
+  the generator.
  */
-QString Generator::linkForExampleFile(const QString &path, const Node *parent)
+QString Generator::linkForExampleFile(const QString &path,
+                                      const Node *parent,
+                                      const QString &fileExt)
 {
     QString link = path;
     QString modPrefix(parent->physicalModuleName());
@@ -460,11 +464,31 @@ QString Generator::linkForExampleFile(const QString &path, const Node *parent)
     QString res;
     transmogrify(link, res);
     res.append(QLatin1Char('.'));
-    res.append(fileExtension());
+    res.append(fileExt);
+    if (fileExt.isEmpty())
+        res.append(fileExtension());
     return res;
 }
 
 /*!
+    Helper function to construct a title for a file or image page
+    included in an example.
+*/
+QString Generator::exampleFileTitle(const ExampleNode *relative,
+                                    const QString &fileName)
+{
+    QString suffix;
+    if (relative->files().contains(fileName))
+        suffix = QLatin1String(" Example File");
+    else if (relative->images().contains(fileName))
+        suffix = QLatin1String(" Image File");
+    else
+        return suffix;
+
+    return fileName.mid(fileName.lastIndexOf(QLatin1Char('/')) + 1) + suffix;
+}
+
+/*!
   If the \a node has a URL, return the URL as the file name.
   Otherwise, construct the file name from the fileBase() and
   either the provided \a extension or fileExtension(), and
@@ -939,62 +963,75 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
             }
         }
     }
+    generateRequiredLinks(node, marker);
+}
+
+/*!
+  Generates either a link to the project folder for example \a node, or a list
+  of links files/images if 'url.examples config' variable is not defined.
+
+  Does nothing for non-example nodes.
+*/
+void Generator::generateRequiredLinks(const Node *node, CodeMarker *marker)
+{
+    if (!node->isExample())
+        return;
+
+    const ExampleNode *en = static_cast<const ExampleNode *>(node);
+    QString exampleUrl = config()->getString(CONFIG_URL + Config::dot + CONFIG_EXAMPLES);
 
-    // 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);
-        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);
+    if (exampleUrl.isEmpty()) {
+        if (!en->noAutoList()) {
+            generateFileList(en, marker, false); // files
+            generateFileList(en, marker, true);  // images
         }
+    } else {
+        generateLinkToExample(en, marker, exampleUrl);
     }
 }
 
 /*!
-  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.
+  Generates an external link to the project folder for example \a node.
+  The path to the example is appended to \a baseUrl string, or to a
+  specific location within the string marked with the placeholder '\1'
+  character.
 */
 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;
+    QString exampleUrl(baseUrl);
+    QString link;
 #ifndef QT_BOOTSTRAPPED
-        link = QUrl(baseUrl).host();
+    link = QUrl(exampleUrl).host();
 #endif
-        if (!link.isEmpty())
-            link.prepend(" @ ");
-        link.prepend("Example project");
+    if (!link.isEmpty())
+        link.prepend(" @ ");
+    link.prepend("Example project");
+
+    const QLatin1Char separator('/');
+    const QLatin1Char placeholder('\1');
+    if (!exampleUrl.contains(placeholder)) {
+        if (!exampleUrl.endsWith(separator))
+            exampleUrl += separator;
+        exampleUrl += placeholder;
+    }
 
-        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;
+    // Construct a path to the example; <install path>/<example name>
+    QStringList path = QStringList()
+        << config()->getString(CONFIG_EXAMPLESINSTALLPATH)
+        << en->name();
+    path.removeAll({});
+
+    Text text;
+    text << Atom::ParaLeft
+         << Atom(Atom::Link, exampleUrl.replace(placeholder, path.join(separator)))
+         << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
+         << Atom(Atom::String, link)
+         << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
+         << Atom::ParaRight;
 
-        generateText(text, 0, marker);
+    generateText(text, 0, marker);
 }
 
 /*!