summaryrefslogtreecommitdiffstats
path: root/src/tools
diff options
context:
space:
mode:
authorJerome Pasion <jerome.pasion@digia.com>2014-06-04 14:44:55 +0200
committerThe Qt Project <gerrit-noreply@qt-project.org>2014-06-11 15:13:29 +0200
commite2a7293290b7aa7090c4ce2178e35eccaea11a00 (patch)
tree3bb475936b8fc11faa1b12c45a144ce0b2674b74 /src/tools
parentde1afe41e3e8abc906d3e4499da61c8b1e4c5bbc (diff)
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>
Diffstat (limited to 'src/tools')
-rw-r--r--src/tools/qdoc/config.cpp7
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc9
-rw-r--r--src/tools/qdoc/htmlgenerator.cpp38
-rw-r--r--src/tools/qdoc/htmlgenerator.h4
4 files changed, 41 insertions, 17 deletions
diff --git a/src/tools/qdoc/config.cpp b/src/tools/qdoc/config.cpp
index 644eab8a56..172ed8015d 100644
--- a/src/tools/qdoc/config.cpp
+++ b/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;
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
index a28e65e976..20cd94c90c 100644
--- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/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.
+
*/
/*!
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();
diff --git a/src/tools/qdoc/htmlgenerator.h b/src/tools/qdoc/htmlgenerator.h
index 395ccdb8bf..787b34daf2 100644
--- a/src/tools/qdoc/htmlgenerator.h
+++ b/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 @@ private:
QString qmltypespage;
QString buildversion;
QString qflagsHref_;
+ int tocDepth;
public:
static bool debugging_on;
@@ -278,6 +279,7 @@ public:
#define HTMLGENERATOR_POSTPOSTHEADER "postpostheader"
#define HTMLGENERATOR_NONAVIGATIONBAR "nonavigationbar"
#define HTMLGENERATOR_NOSUBDIRS "nosubdirs"
+#define HTMLGENERATOR_TOCDEPTH "tocdepth"
QT_END_NAMESPACE