diff options
author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2021-06-24 14:14:43 +0200 |
---|---|---|
committer | Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> | 2021-06-25 10:13:57 +0000 |
commit | 179a026e13baa056641b06a44cb29f165f938cd2 (patch) | |
tree | ecd8d7f54733358ceecfaba9aeb6a4b52f9ec570 /sources/shiboken6/generator | |
parent | ecff7d18b62d8168082dbf59498e4bf01233eb95 (diff) |
shiboken6/doc generator: Extract method to resolve links to QtXmlToSphinxDocGeneratorInterface
Extract the private struct LinkContext to a public struct
QtXmlToSphinxLink with debug operator and add a resolve method to
QtXmlToSphinxDocGeneratorInterface.
Task-number: PYSIDE-1112
Change-Id: I91b3bc45ebc530394a3e77c56b05dd5b740e8985
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit 991cfb9376275e1ab259f0a9b95302bc56ba7127)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
Diffstat (limited to 'sources/shiboken6/generator')
5 files changed, 91 insertions, 58 deletions
diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp index d1de31cef..fd4716e0a 100644 --- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp +++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp @@ -1140,3 +1140,8 @@ const QLoggingCategory &QtDocGenerator::loggingCategory() const { return lcShibokenDoc(); } + +QtXmlToSphinxLink QtDocGenerator::resolveLink(const QtXmlToSphinxLink &link) const +{ + return link; +} diff --git a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h index 2b18d1edd..ab2f2fd45 100644 --- a/sources/shiboken6/generator/qtdoc/qtdocgenerator.h +++ b/sources/shiboken6/generator/qtdoc/qtdocgenerator.h @@ -66,6 +66,7 @@ public: QString resolveContextForMethod(const QString &context, const QString &methodName) const override; const QLoggingCategory &loggingCategory() const override; + QtXmlToSphinxLink resolveLink(const QtXmlToSphinxLink &) const override; protected: bool shouldGenerate(const AbstractMetaClass *) const override; diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp index 6bca4498c..d74982210 100644 --- a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp +++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp @@ -75,58 +75,61 @@ static bool isHttpLink(const QString &ref) return ref.startsWith(u"http://") || ref.startsWith(u"https://"); } -struct QtXmlToSphinx::LinkContext +QDebug operator<<(QDebug d, const QtXmlToSphinxLink &l) { - enum Type - { - Method = 0x1, Function = 0x2, - FunctionMask = Method | Function, - Class = 0x4, Attribute = 0x8, Module = 0x10, - Reference = 0x20, External= 0x40 + static const QHash<QtXmlToSphinxLink::Type, const char *> typeName = { + {QtXmlToSphinxLink::Method, "Method"}, + {QtXmlToSphinxLink::Function, "Function"}, + {QtXmlToSphinxLink::Class, "Class"}, + {QtXmlToSphinxLink::Attribute, "Attribute"}, + {QtXmlToSphinxLink::Module, "Module"}, + {QtXmlToSphinxLink::Reference, "Reference"}, + {QtXmlToSphinxLink::External, "External"}, }; - enum Flags { InsideBold = 0x1, InsideItalic = 0x2 }; - - explicit LinkContext(const QString &ref) : linkRef(ref) {} - - QString linkRef; - QString linkText; - Type type = Reference; - int flags = 0; -}; + QDebugStateSaver saver(d); + d.noquote(); + d.nospace(); + d << "QtXmlToSphinxLinkContext(" << typeName.value(l.type, "") << ", ref=\"" + << l.linkRef << '"'; + if (!l.linkText.isEmpty()) + d << ", text=\"" << l.linkText << '"'; + d << ')'; + return d; +} -static const char *linkKeyWord(QtXmlToSphinx::LinkContext::Type type) +static const char *linkKeyWord(QtXmlToSphinxLink::Type type) { switch (type) { - case QtXmlToSphinx::LinkContext::Method: + case QtXmlToSphinxLink::Method: return ":meth:"; - case QtXmlToSphinx::LinkContext::Function: + case QtXmlToSphinxLink::Function: return ":func:"; - case QtXmlToSphinx::LinkContext::Class: + case QtXmlToSphinxLink::Class: return ":class:"; - case QtXmlToSphinx::LinkContext::Attribute: + case QtXmlToSphinxLink::Attribute: return ":attr:"; - case QtXmlToSphinx::LinkContext::Module: + case QtXmlToSphinxLink::Module: return ":mod:"; - case QtXmlToSphinx::LinkContext::Reference: + case QtXmlToSphinxLink::Reference: return ":ref:"; - case QtXmlToSphinx::LinkContext::External: + case QtXmlToSphinxLink::External: break; - case QtXmlToSphinx::LinkContext::FunctionMask: + case QtXmlToSphinxLink::FunctionMask: break; } return ""; } -TextStream &operator<<(TextStream &str, const QtXmlToSphinx::LinkContext &linkContext) +TextStream &operator<<(TextStream &str, const QtXmlToSphinxLink &linkContext) { // Temporarily turn off bold/italic since links do not work within - if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideBold) + if (linkContext.flags & QtXmlToSphinxLink::InsideBold) str << "**"; - else if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideItalic) + else if (linkContext.flags & QtXmlToSphinxLink::InsideItalic) str << '*'; str << ' ' << linkKeyWord(linkContext.type) << '`'; - const bool isExternal = linkContext.type == QtXmlToSphinx::LinkContext::External; + const bool isExternal = linkContext.type == QtXmlToSphinxLink::External; if (!linkContext.linkText.isEmpty()) { writeEscapedRstText(str, linkContext.linkText); if (isExternal && !linkContext.linkText.endsWith(QLatin1Char(' '))) @@ -134,7 +137,7 @@ TextStream &operator<<(TextStream &str, const QtXmlToSphinx::LinkContext &linkCo str << '<'; } // Convert page titles to RST labels - str << (linkContext.type == QtXmlToSphinx::LinkContext::Reference + str << (linkContext.type == QtXmlToSphinxLink::Reference ? toRstLabel(linkContext.linkRef) : linkContext.linkRef); if (!linkContext.linkText.isEmpty()) str << '>'; @@ -142,9 +145,9 @@ TextStream &operator<<(TextStream &str, const QtXmlToSphinx::LinkContext &linkCo if (isExternal) str << '_'; str << ' '; - if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideBold) + if (linkContext.flags & QtXmlToSphinxLink::InsideBold) str << "**"; - else if (linkContext.flags & QtXmlToSphinx::LinkContext::InsideItalic) + else if (linkContext.flags & QtXmlToSphinxLink::InsideItalic) str << '*'; return str; } @@ -946,21 +949,21 @@ void QtXmlToSphinx::handleLinkTag(QXmlStreamReader& reader) } } -QtXmlToSphinx::LinkContext *QtXmlToSphinx::handleLinkStart(const QString &type, QString ref) const +QtXmlToSphinxLink *QtXmlToSphinx::handleLinkStart(const QString &type, QString ref) const { ref.replace(QLatin1String("::"), QLatin1String(".")); ref.remove(QLatin1String("()")); - auto *result = new LinkContext(ref); + auto *result = new QtXmlToSphinxLink(ref); if (m_insideBold) - result->flags |= LinkContext::InsideBold; + result->flags |= QtXmlToSphinxLink::InsideBold; else if (m_insideItalic) - result->flags |= LinkContext::InsideItalic; + result->flags |= QtXmlToSphinxLink::InsideItalic; if (type == u"external" || isHttpLink(ref)) { - result->type = LinkContext::External; + result->type = QtXmlToSphinxLink::External; } else if (type == functionLinkType() && !m_context.isEmpty()) { - result->type = LinkContext::Method; + result->type = QtXmlToSphinxLink::Method; const auto rawlinklist = QStringView{result->linkRef}.split(QLatin1Char('.')); if (rawlinklist.size() == 1 || rawlinklist.constFirst() == m_context) { const auto lastRawLink = rawlinklist.constLast().toString(); @@ -971,20 +974,20 @@ QtXmlToSphinx::LinkContext *QtXmlToSphinx::handleLinkStart(const QString &type, result->linkRef = m_generator->expandFunction(result->linkRef); } } else if (type == functionLinkType() && m_context.isEmpty()) { - result->type = LinkContext::Function; + result->type = QtXmlToSphinxLink::Function; } else if (type == classLinkType()) { - result->type = LinkContext::Class; + result->type = QtXmlToSphinxLink::Class; result->linkRef = m_generator->expandClass(m_context, result->linkRef); } else if (type == QLatin1String("enum")) { - result->type = LinkContext::Attribute; + result->type = QtXmlToSphinxLink::Attribute; } else if (type == QLatin1String("page")) { // Module, external web page or reference if (result->linkRef == m_parameters.moduleName) - result->type = LinkContext::Module; + result->type = QtXmlToSphinxLink::Module; else - result->type = LinkContext::Reference; + result->type = QtXmlToSphinxLink::Reference; } else { - result->type = LinkContext::Reference; + result->type = QtXmlToSphinxLink::Reference; } return result; } @@ -997,11 +1000,11 @@ QtXmlToSphinx::LinkContext *QtXmlToSphinx::handleLinkStart(const QString &type, // <link raw="Qt::Window" href="qt.html#WindowType-enum" type="enum" enum="Qt::WindowType">Qt::Window</link> // <link raw="QNetworkSession::reject()" href="qnetworksession.html#reject" type="function">QNetworkSession::reject()</link> -static QString fixLinkText(const QtXmlToSphinx::LinkContext *linkContext, +static QString fixLinkText(const QtXmlToSphinxLink *linkContext, QString linktext) { - if (linkContext->type == QtXmlToSphinx::LinkContext::External - || linkContext->type == QtXmlToSphinx::LinkContext::Reference) { + if (linkContext->type == QtXmlToSphinxLink::External + || linkContext->type == QtXmlToSphinxLink::Reference) { return linktext; } // For the language reference documentation, strip the module name. @@ -1013,21 +1016,21 @@ static QString fixLinkText(const QtXmlToSphinx::LinkContext *linkContext, QtXmlToSphinx::stripPythonQualifiers(&linktext); if (linkContext->linkRef == linktext) return QString(); - if ((linkContext->type & QtXmlToSphinx::LinkContext::FunctionMask) != 0 + if ((linkContext->type & QtXmlToSphinxLink::FunctionMask) != 0 && (linkContext->linkRef + QLatin1String("()")) == linktext) { return QString(); } return linktext; } -void QtXmlToSphinx::handleLinkText(LinkContext *linkContext, const QString &linktext) +void QtXmlToSphinx::handleLinkText(QtXmlToSphinxLink *linkContext, const QString &linktext) { linkContext->linkText = fixLinkText(linkContext, linktext); } -void QtXmlToSphinx::handleLinkEnd(LinkContext *linkContext) +void QtXmlToSphinx::handleLinkEnd(QtXmlToSphinxLink *linkContext) { - m_output << *linkContext; + m_output << m_generator->resolveLink(*linkContext); } WebXmlTag QtXmlToSphinx::parentTag() const diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h index cb6bb504a..55d6a79b1 100644 --- a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h +++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.h @@ -39,11 +39,13 @@ #include <QtCore/QTextStream> QT_BEGIN_NAMESPACE +class QDebug; class QXmlStreamReader; QT_END_NAMESPACE class QtXmlToSphinxDocGeneratorInterface; struct QtXmlToSphinxParameters; +struct QtXmlToSphinxLink; enum class WebXmlTag; @@ -52,8 +54,6 @@ class QtXmlToSphinx public: Q_DISABLE_COPY_MOVE(QtXmlToSphinx) - struct LinkContext; - struct InlineImage { QString tag; @@ -168,9 +168,9 @@ private: void handleAnchorTag(QXmlStreamReader& reader); void handleRstPassTroughTag(QXmlStreamReader& reader); - LinkContext *handleLinkStart(const QString &type, QString ref) const; - static void handleLinkText(LinkContext *linkContext, const QString &linktext) ; - void handleLinkEnd(LinkContext *linkContext); + QtXmlToSphinxLink *handleLinkStart(const QString &type, QString ref) const; + static void handleLinkText(QtXmlToSphinxLink *linkContext, const QString &linktext) ; + void handleLinkEnd(QtXmlToSphinxLink *linkContext); WebXmlTag parentTag() const; void warn(const QString &message) const; @@ -183,8 +183,8 @@ private: QStack<StringSharedPtr> m_buffers; // Maintain address stability since it used in TextStream Table m_currentTable; - QScopedPointer<LinkContext> m_linkContext; // for <link> - QScopedPointer<LinkContext> m_seeAlsoContext; // for <see-also>foo()</see-also> + QScopedPointer<QtXmlToSphinxLink> m_linkContext; // for <link> + QScopedPointer<QtXmlToSphinxLink> m_seeAlsoContext; // for <see-also>foo()</see-also> bool m_tableHasHeader = false; QString m_context; const QtXmlToSphinxDocGeneratorInterface *m_generator; @@ -212,4 +212,6 @@ inline TextStream& operator<<(TextStream& s, const QtXmlToSphinx& xmlToSphinx) return s << xmlToSphinx.result(); } +QDebug operator<<(QDebug d, const QtXmlToSphinxLink &l); + #endif // QTXMLTOSPHINX_H diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h b/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h index c4bdedd21..d4e792d76 100644 --- a/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h +++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinxinterface.h @@ -43,6 +43,26 @@ struct QtXmlToSphinxParameters bool snippetComparison = false; }; +struct QtXmlToSphinxLink +{ + enum Type + { + Method = 0x1, Function = 0x2, + FunctionMask = Method | Function, + Class = 0x4, Attribute = 0x8, Module = 0x10, + Reference = 0x20, External= 0x40 + }; + + enum Flags { InsideBold = 0x1, InsideItalic = 0x2 }; + + explicit QtXmlToSphinxLink(const QString &ref) : linkRef(ref) {} + + QString linkRef; + QString linkText; + Type type = Reference; + int flags = 0; +}; + class QtXmlToSphinxDocGeneratorInterface { public: @@ -54,6 +74,8 @@ public: virtual const QLoggingCategory &loggingCategory() const = 0; + virtual QtXmlToSphinxLink resolveLink(const QtXmlToSphinxLink &) const = 0; + virtual ~QtXmlToSphinxDocGeneratorInterface() = default; }; |