AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qdoc: Improve customization of generated html file names

Browse Source 
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>
This commit is contained in:
Venugopal Shivashankar 2015-07-15 15:40:20 +02:00 committed by Topi Reiniö
parent 7a85be3371
commit 831c557cc5
5 changed files with 84 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/tools/qdoc/config.cpp
View File

@ -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");

2
src/tools/qdoc/config.h
View File

@ -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

39
src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
View File

@ -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

67
src/tools/qdoc/generator.cpp
View File

@ -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)
{
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,

4
src/tools/qdoc/generator.h
View File

@ -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;