QDoc: Introduce a variable to set table of contents depth.

-"HTML.tocdepth" variable controls depth value.
-setting to "0" disables table of contents.
-sections 3 and 4 usually don't have descriptive titles
 to warrant their listing in the table of contents.
-table width and CSS (online and offline) don't support wide entries.
-Config class' getInt() function now returns -1 if a variable is
 not set.
-for Qt 5 and projects which use html-config.qdocconf, tocdepth is
 set to "2".
-added variable documentation.

Task-number: QTBUG-38967
Change-Id: Ibd612f5b846ecb9c4b575e7ac11605c6efd2b77c
Reviewed-by: Martin Smith <[email protected]>
Reviewed-by: Venugopal Shivashankar <[email protected]>
Reviewed-by: Sze Howe Koh <[email protected]>
Reviewed-by: Topi Reiniö <[email protected]>

doc/global/html-config.qdocconf

@@ -2,6 +2,8 @@
 
 HTML.nonavigationbar      = "false"
 
+HTML.tocdepth = 2
+
 HTML.extraimages += template/images/arrow_bc.png \
                     template/images/home.png \
                     template/images/ico_out.png \

src/tools/qdoc/config.cpp

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the tools applications of the Qt Toolkit.
@@ -328,11 +328,14 @@ bool Config::getBool(const QString& var) const
   Looks up the configuration variable \a var in the string list
   map. Iterates through the string list found, interpreting each
   string in the list as an integer and adding it to a total sum.
-  Returns the sum.
+  Returns the sum or \c -1 if \a var is not set.
  */
 int Config::getInt(const QString& var) const
 {
     QStringList strs = getStringList(var);
+    if (strs.isEmpty())
+        return -1;
+
     QStringList::ConstIterator s = strs.constBegin();
     int sum = 0;
 

src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -1331,6 +1331,13 @@
     \l qtgui.qdocconf file, and it will copy those specified to the output
     directory alongside the HTML pages.
 
+    \target HTML.tocdepth
+    \section1 HTML.tocdepth
+
+    The HTML.tocdepth variable defines how many document sections are printed in
+    the table of contents. Setting tocdepth to \c 0 disables the table of
+    contents while not setting the variable prints all document sections.
+
 */
 
 /*!

src/tools/qdoc/htmlgenerator.cpp

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the tools applications of the Qt Toolkit.
@@ -169,6 +169,9 @@ void HtmlGenerator::initializeGenerator(const Config &config)
     noNavigationBar = config.getBool(HtmlGenerator::format() +
                                    Config::dot +
                                    HTMLGENERATOR_NONAVIGATIONBAR);
+    tocDepth = config.getInt(HtmlGenerator::format() +
+                              Config::dot +
+                              HTMLGENERATOR_TOCDEPTH);
 
     project = config.getString(CONFIG_PROJECT);
 
@@ -2243,6 +2246,10 @@ void HtmlGenerator::generateTableOfContents(const Node *node,
     if (toc.isEmpty() && !sections && !node->isModule())
         return;
 
+    //turn off table of contents if HTML.tocdepth is set to 0
+    if (tocDepth == 0)
+        return;
+
     QStringList sectionNumber;
     int detailsBase = 0;
 
@@ -2324,18 +2331,23 @@ void HtmlGenerator::generateTableOfContents(const Node *node,
                 sectionNumber.last() = QString::number(sectionNumber.last().toInt() + 1);
             }
         }
-        int numAtoms;
-        Text headingText = Text::sectionHeading(atom);
-        QString s = headingText.toString();
-        out() << "<li class=\"level"
-              << sectionNumber.size()
-              << "\">";
-        out() << "<a href=\""
-              << '#'
-              << Doc::canonicalTitle(s)
-              << "\">";
-        generateAtomList(headingText.firstAtom(), node, marker, true, numAtoms);
-        out() << "</a></li>\n";
+
+        //restrict the ToC depth to the one set by the HTML.tocdepth variable or
+        //print all levels if tocDepth is not set.
+        if (sectionNumber.size() <= tocDepth || tocDepth < 0) {
+            int numAtoms;
+            Text headingText = Text::sectionHeading(atom);
+            QString s = headingText.toString();
+            out() << "<li class=\"level"
+                  << sectionNumber.size()
+                  << "\">";
+            out() << "<a href=\""
+                  << '#'
+                  << Doc::canonicalTitle(s)
+                  << "\">";
+            generateAtomList(headingText.firstAtom(), node, marker, true, numAtoms);
+            out() << "</a></li>\n";
+        }
     }
     while (!sectionNumber.isEmpty()) {
         sectionNumber.removeLast();

src/tools/qdoc/htmlgenerator.h

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the tools applications of the Qt Toolkit.
@@ -265,6 +265,7 @@ class HtmlGenerator : public Generator
     QString qmltypespage;
     QString buildversion;
     QString qflagsHref_;
+    int tocDepth;
 
 public:
     static bool debugging_on;
@@ -278,6 +279,7 @@ class HtmlGenerator : public Generator
 #define HTMLGENERATOR_POSTPOSTHEADER    "postpostheader"
 #define HTMLGENERATOR_NONAVIGATIONBAR   "nonavigationbar"
 #define HTMLGENERATOR_NOSUBDIRS         "nosubdirs"
+#define HTMLGENERATOR_TOCDEPTH          "tocdepth"
 
 
 QT_END_NAMESPACE