Doc: Fixed QDoc's navigation mechanism.

The HTML pages need to display minimal navigation such
as a link to the module landing page or Qt 5's index.html.

-new variables available in qdocconf files:
    navigation.landingpage
    navigation.homepage
    navigation.cppclassespage
    navigation.qmltypespage
    buildversion

The navigation variables are for the new navigation bar.
The buildversion variable is to insert documentation build
information into the pages.

Note about compatibility with Qt Creator docs:
The HTML template files for Qt Creator is retained to keep
Qt Creator compatible with 5.0.x and 5.1.x.

Change-Id: Ibb4d7cada19644204457d822b6b77b2aa7b70f8d
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@digia.com>

3 files changed, 76 insertions, 106 deletions

diff --git a/src/tools/qdoc/config.h b/src/tools/qdoc/config.h
index f23873b8f9..948f31c01a 100644
--- a/src/tools/qdoc/config.h
+++ b/src/tools/qdoc/config.h
@@ -165,7 +165,9 @@ private:
 #define CONFIG_ALIAS                    "alias"
 #define CONFIG_BASE                     "base"
 #define CONFIG_BASEDIR                  "basedir"
+#define CONFIG_BUILDVERSION             "buildversion"
 #define CONFIG_CODEINDENT               "codeindent"
+#define CONFIG_CPPCLASSESPAGE           "cppclassespage"
 #define CONFIG_DEFINES                  "defines"
 #define CONFIG_DEPENDS                  "depends"
 #define CONFIG_DESCRIPTION              "description"
@@ -184,15 +186,18 @@ private:
 #define CONFIG_HEADERS                  "headers"
 #define CONFIG_HEADERSCRIPTS            "headerscripts"
 #define CONFIG_HEADERSTYLES             "headerstyles"
+#define CONFIG_HOMEPAGE                 "homepage"
 #define CONFIG_IGNOREDIRECTIVES         "ignoredirectives"
 #define CONFIG_IGNORETOKENS             "ignoretokens"
 #define CONFIG_IMAGEDIRS                "imagedirs"
 #define CONFIG_IMAGES                   "images"
 #define CONFIG_INDEXES                  "indexes"
 #define CONFIG_LANGUAGE                 "language"
+#define CONFIG_LANDINGPAGE              "landingpage"
 #define CONFIG_MACRO                    "macro"
 #define CONFIG_MANIFESTMETA             "manifestmeta"
 #define CONFIG_NATURALLANGUAGE          "naturallanguage"
+#define CONFIG_NAVIGATION               "navigation"
 #define CONFIG_NOLINKERRORS             "nolinkerrors"
 #define CONFIG_OBSOLETELINKS            "obsoletelinks"
 #define CONFIG_OUTPUTDIR                "outputdir"
@@ -203,6 +208,7 @@ private:
 #define CONFIG_PROJECT                  "project"
 #define CONFIG_REDIRECTDOCUMENTATIONTODEVNULL "redirectdocumentationtodevnull"
 #define CONFIG_QHP                      "qhp"
+#define CONFIG_QMLTYPESPAGE             "qmltypespage"
 #define CONFIG_QUOTINGINFORMATION       "quotinginformation"
 #define CONFIG_SCRIPTDIRS               "scriptdirs"
 #define CONFIG_SCRIPTS                  "scripts"
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index 845ed35b3c..4e8103906e 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -166,9 +166,9 @@ void HtmlGenerator::initializeGenerator(const Config &config)
     pleaseGenerateMacRef = config.getBool(HtmlGenerator::format() +
                                           Config::dot +
                                           HTMLGENERATOR_GENERATEMACREFS);
-    noBreadCrumbs = config.getBool(HtmlGenerator::format() +
+    noNavigationBar = config.getBool(HtmlGenerator::format() +
                                    Config::dot +
-                                   HTMLGENERATOR_NOBREADCRUMBS);
+                                   HTMLGENERATOR_NONAVIGATIONBAR);
 
     project = config.getString(CONFIG_PROJECT);
 
@@ -229,6 +229,25 @@ void HtmlGenerator::initializeGenerator(const Config &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);
+
+    landingpage = config.getString(CONFIG_NAVIGATION
+                                    + Config::dot
+                                    + CONFIG_LANDINGPAGE);
+
+    cppclassespage = config.getString(CONFIG_NAVIGATION
+                                    + Config::dot
+                                    + CONFIG_CPPCLASSESPAGE);
+
+    qmltypespage = config.getString(CONFIG_NAVIGATION
+                                    + Config::dot
+                                    + CONFIG_QMLTYPESPAGE);
+
+    buildversion = config.getString(CONFIG_BUILDVERSION);
 }
 
 /*!
@@ -1616,129 +1635,67 @@ QString HtmlGenerator::fileExtension() const
 }
 
 /*!
-  Output breadcrumb list in the html file.
+  Output navigation list in the html file.
  */
-void HtmlGenerator::generateBreadCrumbs(const QString &title,
+void HtmlGenerator::generateNavigationBar(const QString &title,
                                         const Node *node,
                                         CodeMarker *marker)
 {
-    if (noBreadCrumbs)
+    if (noNavigationBar)
         return;
 
-    Text breadcrumbs;
+    Text navigationbar;
+
+    if (homepage == title)
+        return;
+    if (!homepage.isEmpty())
+        navigationbar << Atom(Atom::ListItemLeft)
+                    << Atom(Atom::AutoLink, homepage)
+                    << Atom(Atom::ListItemRight);
+    if (!landingpage.isEmpty() && landingpage != title)
+        navigationbar << Atom(Atom::ListItemLeft)
+                    << Atom(Atom::AutoLink, landingpage)
+                    << Atom(Atom::ListItemRight);
+
     if (node->type() == Node::Class) {
         const ClassNode *cn = static_cast<const ClassNode *>(node);
         QString name =  node->moduleName();
-        breadcrumbs << Atom(Atom::ListItemLeft)
-                    << Atom(Atom::Link, QLatin1String("All Modules"))
-                    << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                    << Atom(Atom::String, QLatin1String("Modules"))
-                    << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
-                    << Atom(Atom::ListItemRight);
-        if (!name.isEmpty())
-            breadcrumbs << Atom(Atom::ListItemLeft)
-                        << Atom(Atom::AutoLink, name)
+
+        if (!cppclassespage.isEmpty())
+            navigationbar << Atom(Atom::ListItemLeft)
+                        << Atom(Atom::Link, cppclassespage)
+                        << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
+                        << Atom(Atom::String, QLatin1String("C++ Classes"))
+                        << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
                         << Atom(Atom::ListItemRight);
+
         if (!cn->name().isEmpty())
-            breadcrumbs << Atom(Atom::ListItemLeft)
+            navigationbar << Atom(Atom::ListItemLeft)
                         << Atom(Atom::String, protectEnc(cn->name()))
                         << Atom(Atom::ListItemRight);
     }
     else if (node->type() == Node::Document) {
-        const DocNode* fn = static_cast<const DocNode*>(node);
-        if (node->subType() == Node::Module) {
-            breadcrumbs << Atom(Atom::ListItemLeft)
-                        << Atom(Atom::Link, QLatin1String("All Modules"))
+        if (node->subType() == Node::QmlClass || node->subType() == Node::QmlBasicType) {
+            if (!qmltypespage.isEmpty())
+                navigationbar << Atom(Atom::ListItemLeft)
+                        << Atom(Atom::Link, qmltypespage)
                         << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                        << Atom(Atom::String, QLatin1String("Modules"))
+                        << Atom(Atom::String, QLatin1String("QML Types"))
                         << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
                         << Atom(Atom::ListItemRight);
-            QString name =  node->name();
-            if (!name.isEmpty())
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::String, protectEnc(name))
-                            << Atom(Atom::ListItemRight);
-        }
-        else if (node->subType() == Node::Group) {
-            if (fn->name() == QString("modules"))
-                breadcrumbs << Atom(Atom::String, QLatin1String("Modules"));
-            else
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::String, protectEnc(title))
-                            << Atom(Atom::ListItemRight);
-        }
-        else if (node->subType() == Node::Page) {
-            if (fn->name() == QString("qdeclarativeexamples.html")) {
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::Link, QLatin1String("Qt Examples"))
-                            << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                            << Atom(Atom::String, QLatin1String("Examples"))
-                            << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
-                            << Atom(Atom::ListItemRight);
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::AutoLink, QLatin1String("QML Examples & Demos"))
-                            << Atom(Atom::ListItemRight);
-            }
-            else if (fn->name().startsWith("examples-")) {
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::Link, QLatin1String("Qt Examples"))
-                            << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                            << Atom(Atom::String, QLatin1String("Examples"))
-                            << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
-                            << Atom(Atom::ListItemRight);
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::String, protectEnc(title))
-                            << Atom(Atom::ListItemRight);
-            }
-            else if (fn->name() == QString("namespaces.html"))
-                breadcrumbs << Atom(Atom::String, QLatin1String("Namespaces"));
-            else
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::String, protectEnc(title))
-                            << Atom(Atom::ListItemRight);
-        }
-        else if (node->subType() == Node::QmlClass) {
-            breadcrumbs << Atom(Atom::ListItemLeft)
-                        << Atom(Atom::AutoLink, QLatin1String("Basic QML Types"))
-                        << Atom(Atom::ListItemRight);
-            breadcrumbs << Atom(Atom::ListItemLeft)
+
+            navigationbar << Atom(Atom::ListItemLeft)
                         << Atom(Atom::String, protectEnc(title))
                         << Atom(Atom::ListItemRight);
         }
-        else if (node->subType() == Node::Example) {
-            breadcrumbs << Atom(Atom::ListItemLeft)
-                        << Atom(Atom::Link, QLatin1String("Qt Examples"))
-                        << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                        << Atom(Atom::String, QLatin1String("Examples"))
-                        << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
-                        << Atom(Atom::ListItemRight);
-            QStringList sl = fn->name().split('/');
-            if (sl.contains("declarative"))
-                breadcrumbs << Atom(Atom::ListItemLeft)
-                            << Atom(Atom::AutoLink, QLatin1String("QML Examples & Demos"))
-                            << Atom(Atom::ListItemRight);
-            else {
-                QString name = protectEnc("examples-" + sl.at(0) + ".html"); // this generates an empty link
-                QString t = CodeParser::titleFromName(name);
-            }
-            breadcrumbs << Atom(Atom::ListItemLeft)
-                        << Atom(Atom::String, protectEnc(title))
-                        << Atom(Atom::ListItemRight);
+        else {
+            navigationbar << Atom(Atom::ListItemLeft)
+                      << Atom(Atom::String, protectEnc(title))
+                      << Atom(Atom::ListItemRight);
         }
     }
-    else if (node->type() == Node::Namespace) {
-        breadcrumbs << Atom(Atom::ListItemLeft)
-                    << Atom(Atom::Link, QLatin1String("All Namespaces"))
-                    << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-                    << Atom(Atom::String, QLatin1String("Namespaces"))
-                    << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
-                    << Atom(Atom::ListItemRight);
-        breadcrumbs << Atom(Atom::ListItemLeft)
-                    << Atom(Atom::String, protectEnc(title))
-                    << Atom(Atom::ListItemRight);
-    }
 
-    generateText(breadcrumbs, node, marker);
+    generateText(navigationbar, node, marker);
 }
 
 void HtmlGenerator::generateHeader(const QString& title,
@@ -1782,7 +1739,8 @@ void HtmlGenerator::generateHeader(const QString& title,
 #endif
 
     out() << QString(postHeader).replace("\\" + COMMAND_VERSION, qdb_->version());
-    generateBreadCrumbs(title,node,marker);
+    generateNavigationBar(title,node,marker);
+    out() << "<li id=\"buildversion\">\n" << buildversion << "</li>\n";
     out() << QString(postPostHeader).replace("\\" + COMMAND_VERSION, qdb_->version());
 
     navigationLinks.clear();
diff --git a/src/tools/qdoc/htmlgenerator.h b/src/tools/qdoc/htmlgenerator.h
index cdf296e783..15e97588ee 100644
--- a/src/tools/qdoc/htmlgenerator.h
+++ b/src/tools/qdoc/htmlgenerator.h
@@ -127,7 +127,7 @@ private:
     };
 
     const QPair<QString,QString> anchorForNode(const Node *node);
-    void generateBreadCrumbs(const QString& title,
+    void generateNavigationBar(const QString& title,
                              const Node *node,
                              CodeMarker *marker);
     void generateHeader(const QString& title,
@@ -239,7 +239,7 @@ private:
     QString footer;
     QString address;
     bool pleaseGenerateMacRef;
-    bool noBreadCrumbs;
+    bool noNavigationBar;
     QString project;
     QString projectDescription;
     QString projectUrl;
@@ -252,6 +252,12 @@ private:
     QStack<QXmlStreamWriter*> xmlWriterStack;
     static int id;
     QList<ManifestMetaFilter> manifestMetaContent;
+    QString homepage;
+    QString landingpage;
+    QString cppclassespage;
+    QString qmltypespage;
+    QString buildversion;
+
 public:
     static bool debugging_on;
     static QString divNavTop;
@@ -262,9 +268,9 @@ public:
 #define HTMLGENERATOR_GENERATEMACREFS   "generatemacrefs" // ### document me
 #define HTMLGENERATOR_POSTHEADER        "postheader"
 #define HTMLGENERATOR_POSTPOSTHEADER    "postpostheader"
-#define HTMLGENERATOR_NOBREADCRUMBS     "nobreadcrumbs"
+#define HTMLGENERATOR_NONAVIGATIONBAR   "nonavigationbar"
+
 
 QT_END_NAMESPACE
 
 #endif
-