diff options
author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2019-03-25 14:49:47 +0100 |
---|---|---|
committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2019-03-25 15:58:40 +0000 |
commit | 9432862e90bc39c1478a9dd6320201a05a5790cc (patch) | |
tree | 84c3946da73f44b088f91f67488ba789295e4b1c | |
parent | 2d6b78ea3307b0193858d44863f41b1e40645a2f (diff) |
shiboken/Documentation: Move brief to top of class documentation
Extract the <brief> element from the WebXML class description and
place it at the top with an internal reference (More...) to the
detailed description. For this purpose, extend QtXmlToSphinx by a
<rst> element to be able to pass through rst elements as is, which
might come in handy for other purposes as well.
Change-Id: I8e3fd9e3ead99b205afdd5f4be948c0d34336a94
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
-rw-r--r-- | sources/shiboken2/ApiExtractor/abstractmetalang.h | 2 | ||||
-rw-r--r-- | sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp | 43 | ||||
-rw-r--r-- | sources/shiboken2/generator/qtdoc/qtdocgenerator.h | 1 |
3 files changed, 44 insertions, 2 deletions
diff --git a/sources/shiboken2/ApiExtractor/abstractmetalang.h b/sources/shiboken2/ApiExtractor/abstractmetalang.h index 9d36706ac..0c652a39a 100644 --- a/sources/shiboken2/ApiExtractor/abstractmetalang.h +++ b/sources/shiboken2/ApiExtractor/abstractmetalang.h @@ -95,6 +95,8 @@ public: return m_format; } + void setFormat(Format f) { m_format = f; } + private: QString m_data; Format m_format = Documentation::Native; diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp index 9410bc158..05729f4b5 100644 --- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp +++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp @@ -52,6 +52,8 @@ static inline QString nameAttribute() { return QStringLiteral("name"); } static inline QString titleAttribute() { return QStringLiteral("title"); } static inline QString fullTitleAttribute() { return QStringLiteral("fulltitle"); } static inline QString briefAttribute() { return QStringLiteral("brief"); } +static inline QString briefStartElement() { return QStringLiteral("<brief>"); } +static inline QString briefEndElement() { return QStringLiteral("</brief>"); } static inline QString none() { return QStringLiteral("None"); } @@ -336,6 +338,7 @@ QtXmlToSphinx::QtXmlToSphinx(QtDocGenerator* generator, const QString& doc, cons m_handlerMap.insert(QLatin1String("code"), &QtXmlToSphinx::handleCodeTag); m_handlerMap.insert(QLatin1String("badcode"), &QtXmlToSphinx::handleCodeTag); m_handlerMap.insert(QLatin1String("legalese"), &QtXmlToSphinx::handleCodeTag); + m_handlerMap.insert(QLatin1String("rst"), &QtXmlToSphinx::handleRstPassTroughTag); m_handlerMap.insert(QLatin1String("section"), &QtXmlToSphinx::handleAnchorTag); m_handlerMap.insert(QLatin1String("quotefile"), &QtXmlToSphinx::handleQuoteFileTag); @@ -1274,6 +1277,12 @@ void QtXmlToSphinx::handleAnchorTag(QXmlStreamReader& reader) } } +void QtXmlToSphinx::handleRstPassTroughTag(QXmlStreamReader& reader) +{ + if (reader.tokenType() == QXmlStreamReader::Characters) + m_output << reader.text(); +} + void QtXmlToSphinx::handleQuoteFileTag(QXmlStreamReader& reader) { QXmlStreamReader::TokenType token = reader.tokenType(); @@ -1578,6 +1587,30 @@ static void writeInheritedByList(QTextStream& s, const AbstractMetaClass* metaCl s << classes.join(QLatin1String(", ")) << endl << endl; } +// Extract the <brief> section from a WebXML (class) documentation and remove it +// from the source. +static bool extractBrief(Documentation *sourceDoc, Documentation *brief) +{ + if (sourceDoc->format() != Documentation::Native) + return false; + QString value = sourceDoc->value(); + const int briefStart = value.indexOf(briefStartElement()); + if (briefStart < 0) + return false; + const int briefEnd = value.indexOf(briefEndElement(), briefStart + briefStartElement().size()); + if (briefEnd < briefStart) + return false; + const int briefLength = briefEnd + briefEndElement().size() - briefStart; + brief->setFormat(Documentation::Native); + QString briefValue = value.mid(briefStart, briefLength); + briefValue.insert(briefValue.size() - briefEndElement().size(), + QLatin1String("<rst> More_...</rst>")); + brief->setValue(briefValue); + value.remove(briefStart, briefLength); + sourceDoc->setValue(value); + return true; +} + void QtDocGenerator::generateClass(QTextStream &s, GeneratorContext &classContext) { AbstractMetaClass *metaClass = classContext.metaClass(); @@ -1595,6 +1628,11 @@ void QtDocGenerator::generateClass(QTextStream &s, GeneratorContext &classContex s << className << endl; s << Pad('*', className.count()) << endl << endl; + auto documentation = metaClass->documentation(); + Documentation brief; + if (extractBrief(&documentation, &brief)) + writeFormattedText(s, brief, metaClass); + s << ".. inheritance-diagram:: " << getClassTargetFullName(metaClass, true) << endl << " :parts: 2" << endl << endl; // TODO: This would be a parameter in the future... @@ -1615,11 +1653,12 @@ void QtDocGenerator::generateClass(QTextStream &s, GeneratorContext &classContex s << endl << "Detailed Description\n" - "--------------------\n\n"; + "--------------------\n\n" + << ".. _More:\n"; writeInjectDocumentation(s, TypeSystem::DocModificationPrepend, metaClass, 0); if (!writeInjectDocumentation(s, TypeSystem::DocModificationReplace, metaClass, 0)) - writeFormattedText(s, metaClass->documentation(), metaClass); + writeFormattedText(s, documentation, metaClass); if (!metaClass->isNamespace()) writeConstructors(s, metaClass); diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h index 43345716d..21afd0f49 100644 --- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h +++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h @@ -150,6 +150,7 @@ private: void handleUnknownTag(QXmlStreamReader& reader); void handleUselessTag(QXmlStreamReader& reader); void handleAnchorTag(QXmlStreamReader& reader); + void handleRstPassTroughTag(QXmlStreamReader& reader); LinkContext *handleLinkStart(const QString &type, QString ref) const; void handleLinkText(LinkContext *linkContext, const QString &linktext) const; |