qdoc: Improve customization of generated html file names

Introduce 'outputsuffixes' QDoc configuration variable, which
allows defining a module name suffix inserted into the
generated html file names. The suffix can currently be applied
to QML and JS documentation.

This is useful in cases where we have multiple versions
of a module as part of the documentation build, and
writing to a common output directory would otherwise result
in file name clashes.

Change-Id: I1437874fad09f041e506b93b62b6a4a8cae49ec9
Reviewed-by: Martin Smith <martin.smith@digia.com>

5 files changed, 84 insertions, 29 deletions

diff --git a/src/tools/qdoc/config.cpp b/src/tools/qdoc/config.cpp
index 4842c68c92..beb0bae291 100644
--- a/src/tools/qdoc/config.cpp
+++ b/src/tools/qdoc/config.cpp
@@ -91,6 +91,7 @@ QString ConfigStrings::OUTPUTENCODING = QStringLiteral("outputencoding");
 QString ConfigStrings::OUTPUTLANGUAGE = QStringLiteral("outputlanguage");
 QString ConfigStrings::OUTPUTFORMATS = QStringLiteral("outputformats");
 QString ConfigStrings::OUTPUTPREFIXES = QStringLiteral("outputprefixes");
+QString ConfigStrings::OUTPUTSUFFIXES = QStringLiteral("outputsuffixes");
 QString ConfigStrings::PROJECT = QStringLiteral("project");
 QString ConfigStrings::REDIRECTDOCUMENTATIONTODEVNULL = QStringLiteral("redirectdocumentationtodevnull");
 QString ConfigStrings::QHP = QStringLiteral("qhp");
diff --git a/src/tools/qdoc/config.h b/src/tools/qdoc/config.h
index 802bcf929d..8d6a124bd1 100644
--- a/src/tools/qdoc/config.h
+++ b/src/tools/qdoc/config.h
@@ -203,6 +203,7 @@ struct ConfigStrings
     static QString OUTPUTLANGUAGE;
     static QString OUTPUTFORMATS;
     static QString OUTPUTPREFIXES;
+    static QString OUTPUTSUFFIXES;
     static QString PROJECT;
     static QString REDIRECTDOCUMENTATIONTODEVNULL;
     static QString QHP;
@@ -278,6 +279,7 @@ struct ConfigStrings
 #define CONFIG_OUTPUTLANGUAGE ConfigStrings::OUTPUTLANGUAGE
 #define CONFIG_OUTPUTFORMATS ConfigStrings::OUTPUTFORMATS
 #define CONFIG_OUTPUTPREFIXES ConfigStrings::OUTPUTPREFIXES
+#define CONFIG_OUTPUTSUFFIXES ConfigStrings::OUTPUTSUFFIXES
 #define CONFIG_PROJECT ConfigStrings::PROJECT
 #define CONFIG_REDIRECTDOCUMENTATIONTODEVNULL ConfigStrings::REDIRECTDOCUMENTATIONTODEVNULL
 #define CONFIG_QHP ConfigStrings::QHP
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
index 226c107e3a..40576a1da0 100644
--- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -113,6 +113,8 @@
     \li \l {manifestmeta-variable} {manifestmeta}
     \li \l {outputdir-variable} {outputdir}
     \li \l {outputformats-variable} {outputformats}
+    \li \l {outputprefixes-variable} {outputprefixes}
+    \li \l {outputsuffixes-variable} {outputsuffixes}
     \li \l {sourcedirs-variable} {sourcedirs}
     \li \l {sources-variable} {sources}
     \li \l {sources.fileextensions-variable} {sources.fileextensions}
@@ -814,21 +816,48 @@
     Currently, QDoc only supports the HTML format. It is also
     the default format, and doesn't need to be specified.
 
-    \target outputprefixes
+    \target outputprefixes-variable
     \section1 outputprefixes
 
     The \c outputprefixes variable specifies a mapping between types of files
     and the prefixes to prepend to the HTML file names in the generated
     documentation.
 
-    \code
-        outputprefixes = QML
+    \badcode
+        outputprefixes     = QML JS
         outputprefixes.QML = uicomponents-
+        outputprefixes.JS  = uicomponents-
     \endcode
 
     By default, files containing the API documentation for QML types
-    are prefixed with "qml-". In the above example, the
-    prefix \c "uicomponents" is used instead.
+    are prefixed with "qml-", and javaScript types with "js-". In the
+    above example, the prefix \c "uicomponents" is used instead for
+    both.
+
+    The output prefix is applied to file names for documentation on
+    QML and JS types.
+
+    \target outputsuffixes-variable
+    \section1 outputsuffixes
+
+    The \c outputsuffixes variable specifies a mapping between types of
+    files and module name suffixes to append to the HTML file names.
+
+    \badcode
+        outputsuffixes     = QML
+        outputsuffixes.QML = -tp
+    \endcode
+
+    Given a QML module name \e FooBar and the default
+    \l {outputprefixes-variable}{output prefix} ("qml-"), the file name of
+    the generated HTML page for a QML type \e FooWidget would be
+    \c qml-foobar-tp-foowidget.html.
+
+    By default, no suffix is used. The output suffix, if defined, is applied
+    to file names for documentation on QML and JS types, and their respective
+    module pages.
+
+    The \c outputsuffixes variable was introduced in QDoc 5.6.
 
     \target qhp-variable
     \section1 qhp
diff --git a/src/tools/qdoc/generator.cpp b/src/tools/qdoc/generator.cpp
index 831d975591..9f722abe9b 100644
--- a/src/tools/qdoc/generator.cpp
+++ b/src/tools/qdoc/generator.cpp
@@ -63,6 +63,7 @@ QString Generator::outSubdir_;
 QStringList Generator::outFileNames_;
 QSet<QString> Generator::outputFormats;
 QHash<QString, QString> Generator::outputPrefixes;
+QHash<QString, QString> Generator::outputSuffixes;
 QString Generator::project_;
 QStringList Generator::scriptDirs;
 QStringList Generator::scriptFiles;
@@ -329,21 +330,21 @@ QString Generator::fileBase(const Node *node) const
     else if (node->isQmlType() || node->isQmlBasicType() ||
              node->isJsType() || node->isJsBasicType()) {
         base = node->name();
-        if (!node->logicalModuleName().isEmpty()) {
-            base.prepend(node->logicalModuleName() + QLatin1Char('-'));
-        }
         /*
           To avoid file name conflicts in the html directory,
-          we prepend a prefix (by default, "qml-") to the file name of QML
-          element doc files.
+          we prepend a prefix (by default, "qml-") and an optional suffix
+          to the file name. The suffix, if one exists, is appended to the
+          module name.
         */
-        if (node->isQmlType() || node->isQmlBasicType())
-            base.prepend(outputPrefix(QLatin1String("QML")));
-        else
-            base.prepend(outputPrefix(QLatin1String("JS")));
+        if (!node->logicalModuleName().isEmpty()) {
+            base.prepend(node->logicalModuleName()
+                         + outputSuffix(node)
+                         + QLatin1Char('-'));
+        }
+        base.prepend(outputPrefix(node));
     }
     else if (node->isCollectionNode()) {
-        base = node->name();
+        base = node->name() + outputSuffix(node);
         if (base.endsWith(".html"))
             base.truncate(base.length() - 5);
 
@@ -356,7 +357,7 @@ QString Generator::fileBase(const Node *node) const
         else if (node->isModule()) {
             base.append("-module");
         }
-        // Why not add "-group" for gropup pages?
+        // Why not add "-group" for group pages?
     }
     else {
         const Node *p = node;
@@ -519,9 +520,7 @@ QString Generator::fullDocumentLocation(const Node *node, bool useSubdir)
     else if (node->isQmlType() || node->isQmlBasicType() ||
              node->isJsType() || node->isJsBasicType()) {
         QString fb = fileBase(node);
-        if (fb.startsWith(Generator::outputPrefix(QLatin1String("QML"))))
-            return fb + QLatin1Char('.') + currentGenerator()->fileExtension();
-        else if (fb.startsWith(Generator::outputPrefix(QLatin1String("JS"))))
+        if (fb.startsWith(outputPrefix(node)))
             return fb + QLatin1Char('.') + currentGenerator()->fileExtension();
         else {
             QString mq;
@@ -529,10 +528,7 @@ QString Generator::fullDocumentLocation(const Node *node, bool useSubdir)
                 mq = node->logicalModuleName().replace(QChar('.'),QChar('-'));
                 mq = mq.toLower() + QLatin1Char('-');
             }
-            QLatin1String prefix = QLatin1String("QML");
-            if (node->isJsType() || node->isJsBasicType())
-                prefix = QLatin1String("JS");
-            return fdl+ Generator::outputPrefix(prefix) + mq + fileBase(node) +
+            return fdl + outputPrefix(node) + mq + fileBase(node) +
                 QLatin1Char('.') + currentGenerator()->fileExtension();
         }
     }
@@ -1804,15 +1800,24 @@ void Generator::initialize(const Config &config)
 
     project_ = config.getString(CONFIG_PROJECT);
 
-    QStringList prefixes = config.getStringList(CONFIG_OUTPUTPREFIXES);
-    if (!prefixes.isEmpty()) {
-        foreach (const QString &prefix, prefixes)
+    outputPrefixes.clear();
+    QStringList items = config.getStringList(CONFIG_OUTPUTPREFIXES);
+    if (!items.isEmpty()) {
+        foreach (const QString &prefix, items)
             outputPrefixes[prefix] = config.getString(CONFIG_OUTPUTPREFIXES + Config::dot + prefix);
     }
     else {
         outputPrefixes[QLatin1String("QML")] = QLatin1String("qml-");
         outputPrefixes[QLatin1String("JS")] = QLatin1String("js-");
     }
+
+    outputSuffixes.clear();
+    items = config.getStringList(CONFIG_OUTPUTSUFFIXES);
+    if (!items.isEmpty()) {
+        foreach (const QString &suffix, items)
+            outputSuffixes[suffix] = config.getString(CONFIG_OUTPUTSUFFIXES + Config::dot + suffix);
+    }
+
     noLinkErrors_ = config.getBool(CONFIG_NOLINKERRORS);
     autolinkErrors_ = config.getBool(CONFIG_AUTOLINKERRORS);
 }
@@ -1862,9 +1867,25 @@ QString Generator::outFileName()
     return QFileInfo(static_cast<QFile*>(out().device())->fileName()).fileName();
 }
 
-QString Generator::outputPrefix(const QString &nodeType)
+QString Generator::outputPrefix(const Node *node)
+{
+    // Prefix is applied to QML and JS types
+    if (node->isQmlType() || node->isQmlBasicType())
+        return outputPrefixes[QLatin1String("QML")];
+    if (node->isJsType() || node->isJsBasicType())
+        return outputPrefixes[QLatin1String("JS")];
+    return QString();
+}
+
+QString Generator::outputSuffix(const Node *node)
 {
-    return outputPrefixes[nodeType];
+    // Suffix is applied to QML and JS types, as
+    // well as module pages.
+    if (node->isQmlModule() || node->isQmlType() || node->isQmlBasicType())
+        return outputSuffixes[QLatin1String("QML")];
+    if (node->isJsModule() || node->isJsType() || node->isJsBasicType())
+        return outputSuffixes[QLatin1String("JS")];
+    return QString();
 }
 
 bool Generator::parseArg(const QString& src,
diff --git a/src/tools/qdoc/generator.h b/src/tools/qdoc/generator.h
index e4bcd29e52..6c44cd189c 100644
--- a/src/tools/qdoc/generator.h
+++ b/src/tools/qdoc/generator.h
@@ -135,7 +135,8 @@ protected:
     virtual QString typeString(const Node *node);
 
     static bool matchAhead(const Atom *atom, Atom::AtomType expectedAtomType);
-    static QString outputPrefix(const QString &nodeType);
+    static QString outputPrefix(const Node* node);
+    static QString outputSuffix(const Node* node);
     static void singularPlural(Text& text, const NodeList& nodes);
     static void supplementAlsoList(const Node *node, QList<Text> &alsoList);
     static QString trimmedTrailing(const QString &string);
@@ -214,6 +215,7 @@ private:
     static QStringList outFileNames_;
     static QSet<QString> outputFormats;
     static QHash<QString, QString> outputPrefixes;
+    static QHash<QString, QString> outputSuffixes;
     static QStringList scriptDirs;
     static QStringList scriptFiles;
     static QStringList styleDirs;