Examples: Support manifest-defined category order

Reads a separate sorted list of categories from the manifest files.
The first of these lists that is found in the manifest files is used.
For example the Qt documentation defines the list in the manifest file
for qtdoc.

Change-Id: I57c2779862a5ebfc27707b53d43d4ed9e7e8c5f9
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: <github-actions-qt-creator@cristianadam.eu>
Reviewed-by: Christian Stenger <christian.stenger@qt.io>

src/plugins/qtsupport/exampleslistmodel.cpp

@@ -355,13 +355,14 @@ void ExamplesViewController::updateExamples()
                                                                   &qtVersion);
     m_view->clear();
 
+    QStringList categoryOrder;
     QList<ExampleItem *> items;
     for (const QString &exampleSource : sources) {
         const auto manifest = FilePath::fromUserInput(exampleSource);
         qCDebug(log) << QString::fromLatin1("Reading file \"%1\"...")
                             .arg(manifest.absoluteFilePath().toUserOutput());
 
-        const expected_str<QList<ExampleItem *>> result
+        const expected_str<ParsedExamples> result
             = parseExamples(manifest,
                             FilePath::fromUserInput(examplesInstallPath),
                             FilePath::fromUserInput(demosInstallPath),
@@ -371,7 +372,9 @@ void ExamplesViewController::updateExamples()
                          << result.error();
             continue;
         }
-        items += filtered(*result, isValidExampleOrDemo);
+        items += filtered(result->items, isValidExampleOrDemo);
+        if (categoryOrder.isEmpty())
+            categoryOrder = result->categoryOrder;
     }
 
     if (m_isExamples) {
@@ -386,7 +389,8 @@ void ExamplesViewController::updateExamples()
     }
 
     const bool sortIntoCategories = !m_isExamples || qtVersion >= *minQtVersionForCategories;
-    const QStringList order = m_isExamples ? *defaultOrder : QStringList();
+    const QStringList order = categoryOrder.isEmpty() && m_isExamples ? *defaultOrder
+                                                                      : categoryOrder;
     const QList<std::pair<Section, QList<ExampleItem *>>> sections
         = getCategories(items, sortIntoCategories, order, m_isExamples);
     for (int i = 0; i < sections.size(); ++i) {

src/plugins/qtsupport/examplesparser.cpp

@@ -75,6 +75,26 @@ static QHash<QString, QStringList> parseMeta(QXmlStreamReader *reader)
     return result;
 }
 
+static QStringList parseCategories(QXmlStreamReader *reader)
+{
+    QStringList categoryOrder;
+    while (!reader->atEnd()) {
+        switch (reader->readNext()) {
+        case QXmlStreamReader::StartElement:
+            if (reader->name() == QLatin1String("category"))
+                categoryOrder.append(reader->readElementText());
+            break;
+        case QXmlStreamReader::EndElement:
+            if (reader->name() == QLatin1String("categories"))
+                return categoryOrder;
+            break;
+        default:
+            break;
+        }
+    }
+    return categoryOrder;
+}
+
 static QList<ExampleItem *> parseExamples(QXmlStreamReader *reader,
                                           const FilePath &projectsOffset,
                                           const FilePath &examplesInstallPath)
@@ -257,10 +277,10 @@ static QList<ExampleItem *> parseTutorials(QXmlStreamReader *reader, const FileP
     return result;
 }
 
-expected_str<QList<ExampleItem *>> parseExamples(const FilePath &manifest,
+expected_str<ParsedExamples> parseExamples(const FilePath &manifest,
-                                                 const FilePath &examplesInstallPath,
+                                           const FilePath &examplesInstallPath,
-                                                 const FilePath &demosInstallPath,
+                                           const FilePath &demosInstallPath,
-                                                 const bool examples)
+                                           const bool examples)
 {
     const expected_str<QByteArray> contents = manifest.fileContents();
     if (!contents)
@@ -269,19 +289,22 @@ expected_str<QList<ExampleItem *>> parseExamples(const FilePath &manifest,
     return parseExamples(*contents, manifest, examplesInstallPath, demosInstallPath, examples);
 }
 
-expected_str<QList<ExampleItem *>> parseExamples(const QByteArray &manifestData,
+expected_str<ParsedExamples> parseExamples(const QByteArray &manifestData,
-                                                 const Utils::FilePath &manifestPath,
+                                           const Utils::FilePath &manifestPath,
-                                                 const FilePath &examplesInstallPath,
+                                           const FilePath &examplesInstallPath,
-                                                 const FilePath &demosInstallPath,
+                                           const FilePath &demosInstallPath,
-                                                 const bool examples)
+                                           const bool examples)
 {
     const FilePath path = manifestPath.parentDir();
+    QStringList categoryOrder;
     QList<ExampleItem *> items;
     QXmlStreamReader reader(manifestData);
     while (!reader.atEnd()) {
         switch (reader.readNext()) {
         case QXmlStreamReader::StartElement:
-            if (examples && reader.name() == QLatin1String("examples"))
+            if (categoryOrder.isEmpty() && reader.name() == QLatin1String("categories"))
+                categoryOrder = parseCategories(&reader);
+            else if (examples && reader.name() == QLatin1String("examples"))
                 items += parseExamples(&reader, path, examplesInstallPath);
             else if (examples && reader.name() == QLatin1String("demos"))
                 items += parseDemos(&reader, path, demosInstallPath);
@@ -301,7 +324,7 @@ expected_str<QList<ExampleItem *>> parseExamples(const QByteArray &manifestData,
                                    .arg(reader.columnNumber())
                                    .arg(reader.errorString()));
     }
-    return items;
+    return {{items, categoryOrder}};
 }
 
 static bool sortByHighlightedAndName(ExampleItem *first, ExampleItem *second)
@@ -355,7 +378,7 @@ QList<std::pair<Core::Section, QList<ExampleItem *>>> getCategories(const QList<
     } else {
         // All original items have been copied into a category or other, delete.
         qDeleteAll(items);
-        static const int defaultOrderSize = defaultOrder.size();
+        const int defaultOrderSize = defaultOrder.size();
         int index = 0;
         const auto end = categoryMap.constKeyValueEnd();
         for (auto it = categoryMap.constKeyValueBegin(); it != end; ++it) {

src/plugins/qtsupport/examplesparser.h

@@ -31,13 +31,20 @@ public:
     QHash<QString, QStringList> metaData;
 };
 
-QTSUPPORT_TEST_EXPORT Utils::expected_str<QList<ExampleItem *>> parseExamples(
+class QTSUPPORT_TEST_EXPORT ParsedExamples
+{
+public:
+    QList<ExampleItem *> items;
+    QStringList categoryOrder;
+};
+
+QTSUPPORT_TEST_EXPORT Utils::expected_str<ParsedExamples> parseExamples(
     const Utils::FilePath &manifest,
     const Utils::FilePath &examplesInstallPath,
     const Utils::FilePath &demosInstallPath,
     bool examples);
 
-QTSUPPORT_TEST_EXPORT Utils::expected_str<QList<ExampleItem *>> parseExamples(
+QTSUPPORT_TEST_EXPORT Utils::expected_str<ParsedExamples> parseExamples(
     const QByteArray &manifestData,
     const Utils::FilePath &manifestPath,
     const Utils::FilePath &examplesInstallPath,

src/plugins/qtsupport/qtcreator_tutorials.xml

@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <instructionals module="Qt">
+  <categories>
+    <category>Help</category>
+    <category>Learning</category>
+    <category>Online</category>
+    <category>Talk</category>
+  </categories>
   <tutorials>
     <tutorial imageUrl=":qtsupport/images/icons/tutorialicon.png" difficulty="" docUrl="qthelp://org.qt-project.qtcreator/doc/creator-build-example-application.html" projectPath="" name="Building and Running an Example">
       <description><![CDATA[Testing that your installation is successful by opening an existing example application project.]]></description>

tests/auto/examples/tst_examples.cpp

@@ -90,9 +90,11 @@ void tst_Examples::parsing_data()
     QTest::addColumn<QStringList>("platforms");
     QTest::addColumn<MetaData>("metaData");
     QTest::addColumn<QStringList>("categories");
+    QTest::addColumn<QStringList>("categoryOrder");
 
     QTest::addRow("example")
         << QByteArray(R"raw(
+  <instructionals module="Qt">
     <examples>
         <example docUrl="qthelp://org.qt-project.qtwidgets.660/qtwidgets/qtwidgets-widgets-analogclock-example.html"
                  imageUrl="qthelp://org.qt-project.qtwidgets.660/qtwidgets/images/analogclock-example.png"
@@ -110,6 +112,13 @@ void tst_Examples::parsing_data()
             </meta>
         </example>
     </examples>
+    <categories>
+        <category>Application Examples</category>
+        <category>Desktop</category>
+        <category>Mobile</category>
+        <category>Embedded</category>
+    </categories>
+  </instructionals>
  )raw") << /*isExamples=*/true
         << "Analog Clock"
         << "The Analog Clock example shows how to draw the contents of a custom widget."
@@ -126,23 +135,33 @@ void tst_Examples::parsing_data()
         << FilePaths() << Example << true << false << false << ""
         << "" << QStringList()
         << MetaData({{"category", {"Graphics", "Graphics", "Foobar"}}, {"tags", {"widgets"}}})
-        << QStringList{"Foobar", "Graphics"};
+        << QStringList{"Foobar", "Graphics"}
+        << QStringList{"Application Examples", "Desktop", "Mobile", "Embedded"};
 
     QTest::addRow("no category, highlighted")
         << QByteArray(R"raw(
+  <instructionals module="Qt">
     <examples>
         <example name="No Category, highlighted"
                  isHighlighted="true">
         </example>
     </examples>
+  </instructionals>
  )raw") << /*isExamples=*/true
         << "No Category, highlighted" << QString() << QString() << QStringList()
         << FilePath("examples") << QString() << FilePaths() << FilePath() << FilePaths() << Example
         << /*hasSourceCode=*/false << false << /*isHighlighted=*/true << ""
-        << "" << QStringList() << MetaData() << QStringList{"Featured"};
+        << "" << QStringList() << MetaData() << QStringList{"Featured"} << QStringList();
 
     QTest::addRow("tutorial with category")
         << QByteArray(R"raw(
+  <instructionals module="Qt">
+    <categories>
+      <category>Help</category>
+      <category>Learning</category>
+      <category>Online</category>
+      <category>Talk</category>
+    </categories>
     <tutorials>
       <tutorial imageUrl=":qtsupport/images/icons/tutorialicon.png" difficulty="" docUrl="qthelp://org.qt-project.qtcreator/doc/dummytutorial.html" projectPath="" name="A tutorial">
         <description><![CDATA[A dummy tutorial.]]></description>
@@ -152,6 +171,7 @@ void tst_Examples::parsing_data()
         </meta>
       </tutorial>
     </tutorials>
+  </instructionals>
 )raw") << /*isExamples=*/false
         << "A tutorial"
         << "A dummy tutorial."
@@ -160,7 +180,8 @@ void tst_Examples::parsing_data()
         << "qthelp://org.qt-project.qtcreator/doc/dummytutorial.html" << FilePaths() << FilePath()
         << FilePaths() << Tutorial << /*hasSourceCode=*/false << /*isVideo=*/false
         << /*isHighlighted=*/false << QString() << QString() << QStringList()
-        << MetaData({{"category", {"Help"}}}) << QStringList("Help");
+        << MetaData({{"category", {"Help"}}}) << QStringList("Help")
+        << QStringList{"Help", "Learning", "Online", "Talk"};
 }
 
 void tst_Examples::parsing()
@@ -168,16 +189,18 @@ void tst_Examples::parsing()
     QFETCH(QByteArray, data);
     QFETCH(bool, isExamples);
     QFETCH(QStringList, categories);
+    QFETCH(QStringList, categoryOrder);
     const ExampleItem expected = fetchItem();
-    const expected_str<QList<ExampleItem *>> result
+    const expected_str<ParsedExamples> result = parseExamples(data,
-        = parseExamples(data,
+                                                              FilePath(
-                        FilePath("manifest/examples-manifest.xml"),
+                                                                  "manifest/examples-manifest.xml"),
-                        FilePath("examples"),
+                                                              FilePath("examples"),
-                        FilePath("demos"),
+                                                              FilePath("demos"),
-                        isExamples);
+                                                              isExamples);
     QVERIFY(result);
-    QCOMPARE(result->size(), 1);
+    QCOMPARE(result->categoryOrder, categoryOrder);
-    const ExampleItem item = *result->at(0);
+    QCOMPARE(result->items.size(), 1);
+    const ExampleItem item = *result->items.at(0);
     QCOMPARE(item.name, expected.name);
     QCOMPARE(item.description, expected.description);
     QCOMPARE(item.imageUrl, expected.imageUrl);
@@ -197,7 +220,7 @@ void tst_Examples::parsing()
     QCOMPARE(item.metaData, expected.metaData);
 
     const QList<std::pair<Section, QList<ExampleItem *>>> resultCategories
-        = getCategories(*result, true, {}, true);
+        = getCategories(result->items, true, {}, true);
     QCOMPARE(resultCategories.size(), categories.size());
     for (int i = 0; i < resultCategories.size(); ++i) {
         QCOMPARE(resultCategories.at(i).first.name, categories.at(i));