shiboken6/Documentation: Nest inner classes' pages into outer classes

Referencing inner classes like QByteArray::FromBase64Result did not
properly work due to the inner classes being generated to separate
documentation pages.

Change this such that inner classes are nested into the documentation
of the outer class.

The problem though is that this causes excessively long pages for Qt
modules with namespaces like Qt3D/QtDataVisualization (all
deprecated). For them, a type system attribute is added to keep the
old behavior.

Pick-to: 6.8
Task-number: PYSIDE-1106
Change-Id: I51330afa739027c28930af3902b83b1e762b92ef
Reviewed-by: Cristian Maureira-Fredes <[email protected]>

Author: FriedemannKleint

sources/pyside6/PySide6/Qt3DCore/typesystem_3dcore.xml

@@ -4,7 +4,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 -->
 
-<typesystem package="PySide6.Qt3DCore" doc-package="PySide6.Qt3D"
+<typesystem package="PySide6.Qt3DCore" doc-package="PySide6.Qt3D" doc-mode="flat"
             namespace-begin="QT_BEGIN_NAMESPACE" namespace-end="QT_END_NAMESPACE">
     <load-typesystem name="QtGui/typesystem_gui.xml" generate="no"/>
     <smart-pointer-type name="QSharedPointer" type="shared" getter="data"

sources/pyside6/PySide6/Qt3DExtras/typesystem_3dextras.xml

@@ -4,7 +4,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 -->
 
-<typesystem package="PySide6.Qt3DExtras" doc-package="PySide6.Qt3D"
+<typesystem package="PySide6.Qt3DExtras" doc-package="PySide6.Qt3D" doc-mode="flat"
             namespace-begin="QT_BEGIN_NAMESPACE" namespace-end="QT_END_NAMESPACE">
     <load-typesystem name="Qt3DRender/typesystem_3drender.xml" generate="no"/>
     <namespace-type name="Qt3DExtras">

sources/pyside6/PySide6/Qt3DInput/typesystem_3dinput.xml

@@ -4,7 +4,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 -->
 
-<typesystem package="PySide6.Qt3DInput" doc-package="PySide6.Qt3D"
+<typesystem package="PySide6.Qt3DInput" doc-package="PySide6.Qt3D" doc-mode="flat"
             namespace-begin="QT_BEGIN_NAMESPACE" namespace-end="QT_END_NAMESPACE">
     <load-typesystem name="Qt3DCore/typesystem_3dcore.xml" generate="no"/>
     <namespace-type name="Qt3DInput">

sources/pyside6/PySide6/Qt3DLogic/typesystem_3dlogic.xml

@@ -4,7 +4,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 -->
 
-<typesystem package="PySide6.Qt3DLogic" doc-package="PySide6.Qt3D"
+<typesystem package="PySide6.Qt3DLogic" doc-package="PySide6.Qt3D" doc-mode="flat"
             namespace-begin="QT_BEGIN_NAMESPACE" namespace-end="QT_END_NAMESPACE">
     <load-typesystem name="Qt3DCore/typesystem_3dcore.xml" generate="no"/>
     <namespace-type name="Qt3DLogic">

sources/pyside6/PySide6/Qt3DRender/typesystem_3drender.xml

@@ -4,7 +4,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 -->
 
-<typesystem package="PySide6.Qt3DRender" doc-package="PySide6.Qt3D"
+<typesystem package="PySide6.Qt3DRender" doc-package="PySide6.Qt3D" doc-mode="flat"
             namespace-begin="QT_BEGIN_NAMESPACE" namespace-end="QT_END_NAMESPACE">
     <load-typesystem name="Qt3DCore/typesystem_3dcore.xml" generate="no"/>
     <load-typesystem name="QtGui/typesystem_gui.xml" generate="no"/>

sources/pyside6/PySide6/QtDataVisualization/typesystem_datavisualization.xml

@@ -3,7 +3,7 @@
 // Copyright (C) 2017 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 -->
-<typesystem package="PySide6.QtDataVisualization"
+<typesystem package="PySide6.QtDataVisualization" doc-mode="flat"
             namespace-begin="QT_BEGIN_NAMESPACE" namespace-end="QT_END_NAMESPACE">
 
    <extra-includes>

sources/shiboken6/ApiExtractor/typesystem.cpp

@@ -670,6 +670,7 @@ class TypeSystemTypeEntryPrivate : public TypeEntryPrivate
     QString m_namespaceBegin;
     QString m_namespaceEnd;
     QString m_docTargetLangPackage;
+    TypeSystem::DocMode m_docMode = TypeSystem::DocMode::Nested;
 };
 
 TypeSystemTypeEntry::TypeSystemTypeEntry(const QString &entryName, const QVersionNumber &vr,
@@ -737,6 +738,18 @@ void TypeSystemTypeEntry::setDocTargetLangPackage(const QString &p)
     d->m_docTargetLangPackage = p;
 }
 
+TypeSystem::DocMode TypeSystemTypeEntry::docMode() const
+{
+    S_D(const TypeSystemTypeEntry);
+    return d->m_docMode;
+}
+
+void TypeSystemTypeEntry::setDocMode(TypeSystem::DocMode m)
+{
+    S_D(TypeSystemTypeEntry);
+    d->m_docMode = m;
+}
+
 const QString &TypeSystemTypeEntry::namespaceBegin() const
 {
     S_D(const TypeSystemTypeEntry);

sources/shiboken6/ApiExtractor/typesystem_enums.h

@@ -46,6 +46,11 @@ enum DocModificationMode {
     DocModificationXPathReplace
 };
 
+enum class DocMode {
+    Nested,
+    Flat
+};
+
 enum class ExceptionHandling {
     Unspecified,
     Off,

sources/shiboken6/ApiExtractor/typesystemparser.cpp

@@ -89,6 +89,7 @@ constexpr auto overloadNumberAttribute = "overload-number"_L1;
 constexpr auto ownershipAttribute = "owner"_L1;
 constexpr auto packageAttribute = "package"_L1;
 constexpr auto docPackageAttribute = "doc-package"_L1;
+constexpr auto docModeAttribute = "doc-mode"_L1;
 constexpr auto polymorphicBaseAttribute = "polymorphic-base"_L1;
 constexpr auto positionAttribute = "position"_L1;
 constexpr auto preferredConversionAttribute = "preferred-conversion"_L1;
@@ -259,6 +260,14 @@ ENUM_LOOKUP_BEGIN(TypeSystem::PythonEnumType, Qt::CaseSensitive,
     };
 ENUM_LOOKUP_LINEAR_SEARCH
 
+ENUM_LOOKUP_BEGIN(TypeSystem::DocMode, Qt::CaseSensitive,
+                  docModeFromAttribute)
+{
+        {u"nested", TypeSystem::DocMode::Nested},
+        {u"flat", TypeSystem::DocMode::Flat},
+};
+ENUM_LOOKUP_LINEAR_SEARCH
+
 ENUM_LOOKUP_BEGIN(TypeSystem::QtMetaTypeRegistration, Qt::CaseSensitive,
                   qtMetaTypeFromAttribute)
     {
@@ -2096,13 +2105,21 @@ TypeSystemTypeEntryPtr TypeSystemParser::parseRootElement(const ConditionalStrea
     QString namespaceBegin;
     QString namespaceEnd;
     QString docPackage;
+    std::optional<TypeSystem::DocMode> docModeOpt;
 
     for (auto i = attributes->size() - 1; i >= 0; --i) {
         const auto name = attributes->at(i).qualifiedName();
         if (name == packageAttribute) {
             m_defaultPackage = attributes->takeAt(i).value().toString();
         } else if (name == docPackageAttribute) {
            docPackage = attributes->takeAt(i).value().toString();
+        } else if (name == docModeAttribute) {
+            const auto attribute = attributes->takeAt(i);
+            docModeOpt = docModeFromAttribute(attribute.value());
+            if (!docModeOpt.has_value()) {
+                qCWarning(lcShiboken, "%s",
+                          qPrintable(msgInvalidAttributeValue(attribute)));
+            }
         } else if (name == defaultSuperclassAttribute) {
             m_defaultSuperclass = attributes->takeAt(i).value().toString();
         } else if (name == exceptionHandlingAttribute) {
@@ -2158,6 +2175,8 @@ TypeSystemTypeEntryPtr TypeSystemParser::parseRootElement(const ConditionalStrea
     }
     if (!docPackage.isEmpty())
         moduleEntry->setDocTargetLangPackage(docPackage);
+    if (docModeOpt.has_value())
+        moduleEntry->setDocMode(docModeOpt.value());
     moduleEntry->setCodeGeneration(m_generate);
     moduleEntry->setSnakeCase(snakeCase);
     if (!namespaceBegin.isEmpty())

sources/shiboken6/ApiExtractor/typesystemtypeentry.h

@@ -30,6 +30,8 @@ class TypeSystemTypeEntry : public TypeEntry
     bool hasDocTargetLangPackage() const;
     QString docTargetLangPackage() const;
     void setDocTargetLangPackage(const QString &p);
+    TypeSystem::DocMode docMode() const;
+    void setDocMode(TypeSystem::DocMode m);
 
     const QString &namespaceBegin() const;
     void setNamespaceBegin(const QString &n);

sources/shiboken6/doc/typesystem_specifying_types.rst

@@ -50,7 +50,8 @@ It can have a number of attributes, described below.
                 snake-case="yes | no | both"
                 namespace-begin="..."
                 namespace-end="..."
-                doc-package="..." >
+                doc-package="..."
+                doc-mode = "nested | flat" >
     </typesystem>
 
 The **package** attribute is a string describing the package to be used,
@@ -93,6 +94,12 @@ files for the documentation generation. It is mainly relevant for Qt where for
 example the documentation of the ``QtMultimediaWidgets`` module is generated
 into the ``QtMultimedia`` module.
 
+The *optional* attribute **doc-mode** determines whether to nest the
+documentation of inner classes into the outer classes' pages. Its default value
+is **nested**. It is possible to turn this off by specifying **flat** in case
+too many classes are cointained in a namespace, causing excessively long pages.
+However, the referencing may then not fully work.
+
 .. _load-typesystem:
 
 load-typesystem

sources/shiboken6/generator/qtdoc/qtdocgenerator.cpp

@@ -28,6 +28,7 @@
 #include <complextypeentry.h>
 #include <flagstypeentry.h>
 #include <primitivetypeentry.h>
+#include <typesystemtypeentry.h>
 #include <qtdocparser.h>
 #include <doxygenparser.h>
 
@@ -430,13 +431,48 @@ void QtDocGenerator::generateClass(TextStream &s, const QString &targetDir,
                                    const GeneratorContext &classContext,
                                    QList<GeneratorContext> *contexts)
 {
-    Q_UNUSED(targetDir)
-    Q_UNUSED(contexts)
-    AbstractMetaClassCPtr metaClass = classContext.metaClass();
-    qCDebug(lcShibokenDoc).noquote().nospace() << "Generating Documentation for " << metaClass->fullName();
+    generateClassRecursion(s, targetDir, classContext, contexts);
+}
+
+static inline TypeSystem::DocMode classDocMode(const AbstractMetaClassCPtr &metaClass)
+{
+    return typeSystemTypeEntry(metaClass->typeEntry())->docMode();
+}
+
+void QtDocGenerator::generateClassRecursion(TextStream &s, const QString &targetDir,
+                                            const GeneratorContext &classContext,
+                                            QList<GeneratorContext> *contexts)
+{
+    const AbstractMetaClassCPtr &metaClass = classContext.metaClass();
+
+    qCDebug(lcShibokenDoc, "Generating Documentation for %s", qPrintable(metaClass->fullName()));
 
     m_packages[metaClass->package()].classPages << fileNameForContext(classContext);
 
+    doGenerateClass(s, targetDir, metaClass);
+
+    if (classDocMode(metaClass) == TypeSystem::DocMode::Nested) {
+        QList<GeneratorContext> innerContexts;
+        for (qsizetype i = 0; i < contexts->size(); ) {
+            if (contexts->at(i).metaClass()->targetLangEnclosingClass() == metaClass)
+                innerContexts.append(contexts->takeAt(i));
+            else
+                ++i;
+        }
+        if (!innerContexts.isEmpty()) {
+            s << indent;
+            for (const auto &innerClassContext : std::as_const(innerContexts))
+                generateClassRecursion(s, targetDir, innerClassContext, contexts);
+            s << outdent;
+        }
+    }
+}
+
+void QtDocGenerator::doGenerateClass(TextStream &s, const QString &targetDir,
+                                     const AbstractMetaClassCPtr &metaClass)
+{
+    qCDebug(lcShibokenDoc).noquote().nospace() << "Generating Documentation for " << metaClass->fullName();
+
     m_docParser->setPackageName(metaClass->package());
     const QString sourceFile =
         m_docParser->fillDocumentation(std::const_pointer_cast<AbstractMetaClass>(metaClass));

sources/shiboken6/generator/qtdoc/qtdocgenerator.h

@@ -64,6 +64,11 @@ class QtDocGenerator : public Generator, public QtXmlToSphinxDocGeneratorInterfa
     bool finishGeneration() override;
 
 private:
+    void generateClassRecursion(TextStream &s, const QString &targetDir,
+                                const GeneratorContext &classContext,
+                                QList<GeneratorContext> *contexts);
+    void doGenerateClass(TextStream &ts, const QString &targetDir,
+                         const AbstractMetaClassCPtr &metaClass);
     void writeEnums(TextStream &s, const AbstractMetaEnumList &enums,
                     const QString &scope, QtXmlToSphinxImages *images) const;