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 <martin.smith@digia.com>
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

1 files changed, 25 insertions, 13 deletions

diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index be8c68fc11..7547177eb3 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/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();