Skip to content

Commit 251962a

Browse files
jcollins-gjcollins-g
authored
Fix category order not recognized problem (#1758)
* Fix bugs in new category support * Rebuild docs and update version
1 parent baa9f19 commit 251962a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+168
-163
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
## 0.21.1
2+
* Fix a problem where category ordering specified in categories option
3+
was not obeyed. Reintroduce categoryOrder option to solve this problem.
4+
15
## 0.21.0
26
* Expand categories to all top level items as well as libraries. (#1681, #1353)
37
* The categoryOrder option in dartdoc_options.yaml and the command line

‎README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,15 +109,18 @@ dartdoc:
109109
"Second Category":
110110
markdown: doc/Second.md
111111
name: Great
112+
categoryOrder: ["First Category", "Second Category"]
112113
linkTo:
113114
url: "https://my.dartdocumentationsite.org/dev/%v%"
114115
```
115116
116117
Unrecognized options will be ignored. Supported options:
117118
118-
* **categories**: Specify the order of categories. For APIs you'd like to document, specify
119+
* **categories**: More details for each category/topic. For topics you'd like to document, specify
119120
the markdown file with `markdown:` to use for the category page. Optionally, rename the
120121
category from the source code into a display name with 'name:'.
122+
* **categoryOrder**: Specify the order of topics for display in the sidebar and
123+
the package page.
121124
* **exclude**: Specify a list of library names to avoid generating docs for,
122125
overriding any specified in include.
123126
* **include**: Specify a list of library names to generate docs for, ignoring all others.

‎lib/src/dartdoc_options.dart

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -77,24 +77,19 @@ class CategoryConfiguration {
7777
/// A map of [CategoryDefinition.name] to [CategoryDefinition] objects.
7878
final Map<String, CategoryDefinition> categoryDefinitions;
7979

80-
/// The defined order for categories.
81-
List<String> categoryOrder;
82-
83-
CategoryConfiguration._(this.categoryDefinitions, this.categoryOrder);
80+
CategoryConfiguration._(this.categoryDefinitions);
8481

8582
static CategoryConfiguration get empty {
86-
return new CategoryConfiguration._({}, []);
83+
return new CategoryConfiguration._({});
8784
}
8885

8986
static CategoryConfiguration fromYamlMap(
9087
YamlMap yamlMap, pathLib.Context pathContext) {
91-
List<String> categoriesInOrder = [];
9288
Map<String, CategoryDefinition> newCategoryDefinitions = {};
9389
for (MapEntry entry in yamlMap.entries) {
9490
String name = entry.key.toString();
9591
String displayName;
9692
String documentationMarkdown;
97-
categoriesInOrder.add(name);
9893
var categoryMap = entry.value;
9994
if (categoryMap is Map) {
10095
displayName = categoryMap['displayName']?.toString();
@@ -111,8 +106,7 @@ class CategoryConfiguration {
111106
new CategoryDefinition(name, displayName, documentationMarkdown);
112107
}
113108
}
114-
return new CategoryConfiguration._(
115-
newCategoryDefinitions, categoriesInOrder);
109+
return new CategoryConfiguration._(newCategoryDefinitions);
116110
}
117111
}
118112

@@ -1014,6 +1008,7 @@ class DartdocOptionContext {
10141008
optionSet['ambiguousReexportScorerMinConfidence'].valueAt(context);
10151009
bool get autoIncludeDependencies =>
10161010
optionSet['autoIncludeDependencies'].valueAt(context);
1011+
List<String> get categoryOrder => optionSet['categoryOrder'].valueAt(context);
10171012
CategoryConfiguration get categories =>
10181013
optionSet['categories'].valueAt(context);
10191014
List<String> get dropTextFrom => optionSet['dropTextFrom'].valueAt(context);
@@ -1068,7 +1063,6 @@ Future<List<DartdocOption>> createDartdocOptions() async {
10681063
new DartdocOptionArgOnly<bool>('addCrossdart', false,
10691064
help: 'Add Crossdart links to the source code pieces.',
10701065
negatable: true),
1071-
10721066
new DartdocOptionArgFile<double>(
10731067
'ambiguousReexportScorerMinConfidence', 0.1,
10741068
help:
@@ -1077,6 +1071,10 @@ Future<List<DartdocOption>> createDartdocOptions() async {
10771071
help:
10781072
'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',
10791073
negatable: true),
1074+
new DartdocOptionArgFile<List<String>>('categoryOrder', [],
1075+
help:
1076+
"A list of categories (not package names) to place first when grouping symbols on dartdoc's sidebar. "
1077+
'Unmentioned categories are sorted after these.'),
10801078
new DartdocOptionFileOnly<CategoryConfiguration>(
10811079
'categories', CategoryConfiguration.empty,
10821080
convertYamlToType: CategoryConfiguration.fromYamlMap,
@@ -1206,7 +1204,7 @@ Future<List<DartdocOption>> createDartdocOptions() async {
12061204
new DartdocOptionArgOnly<List<String>>('packageOrder', [],
12071205
help:
12081206
'A list of package names to place first when grouping libraries in packages. '
1209-
'Unmentioned categories are sorted after these.'),
1207+
'Unmentioned packages are sorted after these.'),
12101208
new DartdocOptionArgOnly<bool>('sdkDocs', false,
12111209
help: 'Generate ONLY the docs for the Dart SDK.', negatable: false),
12121210
new DartdocOptionArgSynth<String>('sdkDir',

‎lib/src/model.dart

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,6 @@ abstract class Inheritable implements ModelElement {
149149
// starting from the ModelElement.
150150
if (canonicalC != null) {
151151
assert(canonicalC.isCanonical);
152-
//assert(this.inheritance.contains(canonicalC));
153152
assert(canonicalC.contains(searchElement));
154153
_canonicalEnclosingClass = canonicalC;
155154
break;
@@ -5131,7 +5130,7 @@ class Category extends Nameable
51315130
String get sortKey => _name;
51325131

51335132
@override
5134-
List<String> get containerOrder => config.categories.categoryOrder;
5133+
List<String> get containerOrder => config.categoryOrder;
51355134

51365135
@override
51375136
String get enclosingName => package.name;

‎lib/src/version.dart

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: dartdoc
22
# Also update the `version` field in lib/dartdoc.dart.
3-
version: 0.21.0
3+
version: 0.21.1
44
author: Dart Team <[email protected]>
55
description: A documentation generator for Dart.
66
homepage: https://github.com/dart-lang/dartdoc

‎test/model_test.dart

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,14 +189,14 @@ void main() {
189189
packageCategories.map((c) => c.name).toList(),
190190
orderedEquals([
191191
'Superb',
192-
'Real Libraries',
193192
'Unreal',
193+
'Real Libraries',
194194
'Misc',
195195
'More Excellence',
196196
'NotSoExcellent'
197197
]));
198198
expect(packageCategories.map((c) => c.libraries.length).toList(),
199-
orderedEquals([0, 3, 2, 1, 0, 0]));
199+
orderedEquals([0, 2, 3, 1, 0, 0]));
200200
expect(
201201
packageGraph
202202
.localPackages.first.defaultCategory.publicLibraries.length,

‎testing/test_package/dartdoc_options.yaml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
dartdoc:
2+
categoryOrder: ["Excellent", "Unreal", "Real Libraries"]
23
categories:
34
Excellent:
45
markdown: "Excellent.md"
56
displayName: "Superb"
6-
Real Libraries:
77
Unreal:
88
markdown: "Unreal.md"
9+
Real Libraries:

‎testing/test_package_docs/__404error.html

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<meta charset="utf-8">
55
<meta http-equiv="X-UA-Compatible" content="IE=edge">
66
<meta name="viewport" content="width=device-width, initial-scale=1">
7-
<meta name="generator" content="made with love by dartdoc 0.21.0">
7+
<meta name="generator" content="made with love by dartdoc 0.21.1">
88
<meta name="description" content="test_package API docs, for the Dart programming language.">
99
<title>test_package - Dart API docs</title>
1010

@@ -42,13 +42,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4242
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4343
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4444
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
45+
<li class="section-subtitle">Unreal</li>
46+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
47+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4548
<li class="section-subtitle">Real Libraries</li>
4649
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
4750
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
4851
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
49-
<li class="section-subtitle">Unreal</li>
50-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
51-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5252
<li class="section-subtitle">Misc</li>
5353
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5454
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/anonymous_library/anonymous_library-library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4545
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4646
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4747
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
48+
<li class="section-subtitle">Unreal</li>
49+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
50+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4851
<li class="section-subtitle">Real Libraries</li>
4952
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
5053
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
5154
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
52-
<li class="section-subtitle">Unreal</li>
53-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
54-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5555
<li class="section-subtitle">Misc</li>
5656
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5757
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/another_anonymous_lib/another_anonymous_lib-library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4545
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4646
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4747
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
48+
<li class="section-subtitle">Unreal</li>
49+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
50+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4851
<li class="section-subtitle">Real Libraries</li>
4952
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
5053
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
5154
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
52-
<li class="section-subtitle">Unreal</li>
53-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
54-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5555
<li class="section-subtitle">Misc</li>
5656
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5757
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/categoriesExported/categoriesExported-library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4545
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4646
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4747
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
48+
<li class="section-subtitle">Unreal</li>
49+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
50+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4851
<li class="section-subtitle">Real Libraries</li>
4952
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
5053
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
5154
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
52-
<li class="section-subtitle">Unreal</li>
53-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
54-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5555
<li class="section-subtitle">Misc</li>
5656
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5757
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/code_in_comments/code_in_comments-library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4545
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4646
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4747
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
48+
<li class="section-subtitle">Unreal</li>
49+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
50+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4851
<li class="section-subtitle">Real Libraries</li>
4952
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
5053
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
5154
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
52-
<li class="section-subtitle">Unreal</li>
53-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
54-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5555
<li class="section-subtitle">Misc</li>
5656
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5757
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/css/css-library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4545
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4646
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4747
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
48+
<li class="section-subtitle">Unreal</li>
49+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
50+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4851
<li class="section-subtitle">Real Libraries</li>
4952
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
5053
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
5154
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
52-
<li class="section-subtitle">Unreal</li>
53-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
54-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5555
<li class="section-subtitle">Misc</li>
5656
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5757
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/ex/ex-library.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,13 @@ <h5><span class="package-name">test_package</span> <span class="package-kind">pa
4545
<li><a href="another_anonymous_lib/another_anonymous_lib-library.html">another_anonymous_lib</a></li>
4646
<li><a href="code_in_comments/code_in_comments-library.html">code_in_comments</a></li>
4747
<li><a class="deprecated" href="is_deprecated/is_deprecated-library.html">is_deprecated</a></li>
48+
<li class="section-subtitle">Unreal</li>
49+
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
50+
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
4851
<li class="section-subtitle">Real Libraries</li>
4952
<li class="section-subitem"><a href="ex/ex-library.html">ex</a></li>
5053
<li class="section-subitem"><a href="fake/fake-library.html">fake</a></li>
5154
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
52-
<li class="section-subtitle">Unreal</li>
53-
<li class="section-subitem"><a href="reexport_one/reexport_one-library.html">reexport_one</a></li>
54-
<li class="section-subitem"><a href="reexport_two/reexport_two-library.html">reexport_two</a></li>
5555
<li class="section-subtitle">Misc</li>
5656
<li class="section-subitem"><a href="two_exports/two_exports-library.html">two_exports</a></li>
5757
<li class="section-subtitle">Other</li>

‎testing/test_package_docs/fake/BaseForDocComments-class.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ <h5>fake library</h5>
161161

162162
<div class="col-xs-12 col-sm-9 col-md-8 main-content">
163163
<h1>BaseForDocComments class <span class="category superb cp-0 linked" title="This is part of the Superb Topic."><a href="topics/Superb-topic.html">Superb</a></span>
164-
<span class="category unreal cp-2 linked" title="This is part of the Unreal Topic."><a href="topics/Unreal-topic.html">Unreal</a></span>
164+
<span class="category unreal cp-1 linked" title="This is part of the Unreal Topic."><a href="topics/Unreal-topic.html">Unreal</a></span>
165165
</h1>
166166

167167
<section class="desc markdown">

0 commit comments

Comments
 (0)