From 9432862e90bc39c1478a9dd6320201a05a5790cc Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Mon, 25 Mar 2019 14:49:47 +0100 Subject: shiboken/Documentation: Move brief to top of class documentation Extract the 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 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 --- sources/shiboken2/ApiExtractor/abstractmetalang.h | 2 + .../shiboken2/generator/qtdoc/qtdocgenerator.cpp | 43 +++++++++++++++++++++- sources/shiboken2/generator/qtdoc/qtdocgenerator.h | 1 + 3 files changed, 44 insertions(+), 2 deletions(-) (limited to 'sources/shiboken2') 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(""); } +static inline QString briefEndElement() { return QStringLiteral(""); } 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 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(" More_...")); + 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; -- cgit v1.2.3