From 831c557cc5c2e06d41bfe815450d50cb8be18354 Mon Sep 17 00:00:00 2001 From: Venugopal Shivashankar Date: Wed, 15 Jul 2015 15:40:20 +0200 Subject: [PATCH] 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 --- src/tools/qdoc/config.cpp | 1 + src/tools/qdoc/config.h | 2 + src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc | 39 ++++++++++-- src/tools/qdoc/generator.cpp | 67 +++++++++++++------- src/tools/qdoc/generator.h | 4 +- 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 Generator::outputFormats; QHash Generator::outputPrefixes; +QHash 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(out().device())->fileName()).fileName(); } -QString Generator::outputPrefix(const QString &nodeType) +QString Generator::outputPrefix(const Node *node) { - return outputPrefixes[nodeType]; + // 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) +{ + // 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 &alsoList); static QString trimmedTrailing(const QString &string); @@ -214,6 +215,7 @@ private: static QStringList outFileNames_; static QSet outputFormats; static QHash outputPrefixes; + static QHash outputSuffixes; static QStringList scriptDirs; static QStringList scriptFiles; static QStringList styleDirs;