Fix category order not recognized problem (#1758)

* Fix bugs in new category support

* Rebuild docs and update version

Author: jcollins-g

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.21.1
+* Fix a problem where category ordering specified in categories option
+  was not obeyed.  Reintroduce categoryOrder option to solve this problem.
+
 ## 0.21.0
 * Expand categories to all top level items as well as libraries.  (#1681, #1353)
 * The categoryOrder option in dartdoc_options.yaml and the command line

README.md

@@ -109,15 +109,18 @@ dartdoc:
     "Second Category":
       markdown: doc/Second.md
       name: Great
+  categoryOrder: ["First Category", "Second Category"]
   linkTo:
     url: "https://my.dartdocumentationsite.org/dev/%v%"
 ```
 
 Unrecognized options will be ignored.  Supported options:
 
-  * **categories**:  Specify the order of categories.  For APIs you'd like to document, specify
+  * **categories**:  More details for each category/topic.  For topics you'd like to document, specify
     the markdown file with `markdown:` to use for the category page.  Optionally, rename the
     category from the source code into a display name with 'name:'.
+  * **categoryOrder**:  Specify the order of topics for display in the sidebar and
+    the package page.
   * **exclude**:  Specify a list of library names to avoid generating docs for,
     overriding any specified in include.
   * **include**:  Specify a list of library names to generate docs for, ignoring all others.

lib/src/dartdoc_options.dart

@@ -77,24 +77,19 @@ class CategoryConfiguration {
   /// A map of [CategoryDefinition.name] to [CategoryDefinition] objects.
   final Map<String, CategoryDefinition> categoryDefinitions;
 
-  /// The defined order for categories.
-  List<String> categoryOrder;
-
-  CategoryConfiguration._(this.categoryDefinitions, this.categoryOrder);
+  CategoryConfiguration._(this.categoryDefinitions);
 
   static CategoryConfiguration get empty {
-    return new CategoryConfiguration._({}, []);
+    return new CategoryConfiguration._({});
   }
 
   static CategoryConfiguration fromYamlMap(
       YamlMap yamlMap, pathLib.Context pathContext) {
-    List<String> categoriesInOrder = [];
     Map<String, CategoryDefinition> newCategoryDefinitions = {};
     for (MapEntry entry in yamlMap.entries) {
       String name = entry.key.toString();
       String displayName;
       String documentationMarkdown;
-      categoriesInOrder.add(name);
       var categoryMap = entry.value;
       if (categoryMap is Map) {
         displayName = categoryMap['displayName']?.toString();
@@ -111,8 +106,7 @@ class CategoryConfiguration {
             new CategoryDefinition(name, displayName, documentationMarkdown);
       }
     }
-    return new CategoryConfiguration._(
-        newCategoryDefinitions, categoriesInOrder);
+    return new CategoryConfiguration._(newCategoryDefinitions);
   }
 }
 
@@ -1014,6 +1008,7 @@ class DartdocOptionContext {
       optionSet['ambiguousReexportScorerMinConfidence'].valueAt(context);
   bool get autoIncludeDependencies =>
       optionSet['autoIncludeDependencies'].valueAt(context);
+  List<String> get categoryOrder => optionSet['categoryOrder'].valueAt(context);
   CategoryConfiguration get categories =>
       optionSet['categories'].valueAt(context);
   List<String> get dropTextFrom => optionSet['dropTextFrom'].valueAt(context);
@@ -1068,7 +1063,6 @@ Future<List<DartdocOption>> createDartdocOptions() async {
     new DartdocOptionArgOnly<bool>('addCrossdart', false,
         help: 'Add Crossdart links to the source code pieces.',
         negatable: true),
-
     new DartdocOptionArgFile<double>(
         'ambiguousReexportScorerMinConfidence', 0.1,
         help:
@@ -1077,6 +1071,10 @@ Future<List<DartdocOption>> createDartdocOptions() async {
         help:
             'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',
         negatable: true),
+    new DartdocOptionArgFile<List<String>>('categoryOrder', [],
+        help:
+            "A list of categories (not package names) to place first when grouping symbols on dartdoc's sidebar. "
+            'Unmentioned categories are sorted after these.'),
     new DartdocOptionFileOnly<CategoryConfiguration>(
         'categories', CategoryConfiguration.empty,
         convertYamlToType: CategoryConfiguration.fromYamlMap,
@@ -1206,7 +1204,7 @@ Future<List<DartdocOption>> createDartdocOptions() async {
     new DartdocOptionArgOnly<List<String>>('packageOrder', [],
         help:
             'A list of package names to place first when grouping libraries in packages. '
-            'Unmentioned categories are sorted after these.'),
+            'Unmentioned packages are sorted after these.'),
     new DartdocOptionArgOnly<bool>('sdkDocs', false,
         help: 'Generate ONLY the docs for the Dart SDK.', negatable: false),
     new DartdocOptionArgSynth<String>('sdkDir',

lib/src/model.dart

@@ -149,7 +149,6 @@ abstract class Inheritable implements ModelElement {
             // starting from the ModelElement.
             if (canonicalC != null) {
               assert(canonicalC.isCanonical);
-              //assert(this.inheritance.contains(canonicalC));
               assert(canonicalC.contains(searchElement));
               _canonicalEnclosingClass = canonicalC;
               break;
@@ -5131,7 +5130,7 @@ class Category extends Nameable
   String get sortKey => _name;
 
   @override
-  List<String> get containerOrder => config.categories.categoryOrder;
+  List<String> get containerOrder => config.categoryOrder;
 
   @override
   String get enclosingName => package.name;

lib/src/version.dart

@@ -1,6 +1,6 @@
 name: dartdoc
 # Also update the `version` field in lib/dartdoc.dart.
-version: 0.21.0
+version: 0.21.1
 author: Dart Team <[email protected]>
 description: A documentation generator for Dart.
 homepage: https://github.com/dart-lang/dartdoc

pubspec.yaml

@@ -189,14 +189,14 @@ void main() {
           packageCategories.map((c) => c.name).toList(),
           orderedEquals([
             'Superb',
-            'Real Libraries',
             'Unreal',
+            'Real Libraries',
             'Misc',
             'More Excellence',
             'NotSoExcellent'
           ]));
       expect(packageCategories.map((c) => c.libraries.length).toList(),
-          orderedEquals([0, 3, 2, 1, 0, 0]));
+          orderedEquals([0, 2, 3, 1, 0, 0]));
       expect(
           packageGraph
               .localPackages.first.defaultCategory.publicLibraries.length,

test/model_test.dart

@@ -1,8 +1,9 @@
 dartdoc:
+  categoryOrder: ["Excellent", "Unreal", "Real Libraries"]
   categories:
     Excellent:
       markdown: "Excellent.md"
       displayName: "Superb"
-    Real Libraries:
     Unreal:
       markdown: "Unreal.md"
+    Real Libraries:

testing/test_package/dartdoc_options.yaml

@@ -4,7 +4,7 @@
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <meta name="generator" content="made with love by dartdoc 0.21.0">
+  <meta name="generator" content="made with love by dartdoc 0.21.1">
   <meta name="description" content="test_package API docs, for the Dart programming language.">
   <title>test_package - Dart API docs</title>
 
@@ -42,13 +42,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
           <li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
           <li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
           <li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
+          <li class="section-subtitle">Unreal</li>
+            <li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
+            <li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
           <li class="section-subtitle">Real Libraries</li>
             <li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
             <li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
             <li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
-          <li class="section-subtitle">Unreal</li>
-            <li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
-            <li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
           <li class="section-subtitle">Misc</li>
             <li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
           <li class="section-subtitle">Other</li>

testing/test_package_docs/__404error.html

@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
           <li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
           <li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
           <li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
+          <li class="section-subtitle">Unreal</li>
+            <li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
+            <li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
           <li class="section-subtitle">Real Libraries</li>
             <li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
             <li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
             <li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
-          <li class="section-subtitle">Unreal</li>
-            <li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
-            <li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
           <li class="section-subtitle">Misc</li>
             <li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
           <li class="section-subtitle">Other</li>