Implement basic categorization for libraries in dartdoc (#1641)

* Squash changes

* Update README with usage for categories.

* review comments

Author: jcollins-g

README.md

@@ -95,6 +95,34 @@ authoring doc comments for Dart with `dartdoc`.
 
 ## Advanced features
 
+### dartdoc_options.yaml
+
+Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc
+generates docs.  
+
+```yaml
+dartdoc:
+  categoryOrder: ["First Category", "Second Category"]
+
+```
+For now, there's only one option:
+
+  * **categoryOrder**:  Specify the order of categories, below, for display in the sidebar and
+    the package page.
+  
+### Categories
+
+You can tag libraries in their documentation with the string `{@category YourCategory}`, and
+that will cause the library to appear in a category when showing the sidebar on the Package
+and Library pages.
+
+```dart
+/// Here is my library.
+/// 
+/// {@category Amazing}
+library my_library;
+```
+
 ### Macros
 
 You can specify "macros", i.e. reusable pieces of documentation. For that, first specify a template

bin/dartdoc.dart

@@ -192,7 +192,8 @@ main(List<String> arguments) async {
   PackageMeta packageMeta = new PackageMeta.fromDir(inputDir);
 
   if (packageMeta == null) {
-    stderr.writeln(' fatal error: Unable to generate documentation: no pubspec.yaml found');
+    stderr.writeln(
+        ' fatal error: Unable to generate documentation: no pubspec.yaml found');
     exit(1);
   }
 
@@ -212,7 +213,6 @@ main(List<String> arguments) async {
     }
   }
 
-
   logInfo("Generating documentation for '${packageMeta}' into "
       "${outputDir.absolute.path}${Platform.pathSeparator}");
 
@@ -221,7 +221,6 @@ main(List<String> arguments) async {
       footerFilePaths: footerFilePaths,
       footerTextFilePaths: footerTextFilePaths,
       faviconPath: args['favicon'],
-      displayAsPackages: args['use-categories'],
       prettyIndexJson: args['pretty-index-json']);
 
   for (var generator in generators) {
@@ -311,10 +310,8 @@ ArgParser _createArgsParser() {
   parser.addFlag('show-progress',
       help: 'Display progress indications to console stdout', negatable: false);
   parser.addOption('sdk-readme',
-      help:
-          'Path to the SDK description file.  Deprecated (ignored)');
-  parser.addOption('input',
-      help: 'Path to source directory.');
+      help: 'Path to the SDK description file.  Deprecated (ignored)');
+  parser.addOption('input', help: 'Path to source directory.');
   parser.addOption('output',
       help: 'Path to output directory.', defaultsTo: defaultOutDir);
   parser.addMultiOption('header',
@@ -349,22 +346,18 @@ ArgParser _createArgsParser() {
       help: 'A path to a favicon for the generated docs.');
   parser.addFlag('use-categories',
       help:
-          'Group libraries from the same package in the libraries sidebar. (deprecated, replaced by display-as-packages)',
-      negatable: false,
-      defaultsTo: false);
-  parser.addFlag('display-as-packages',
-      help: 'Group libraries from the same package in the libraries sidebar.',
+          'Group libraries from the same package in the libraries sidebar. (deprecated, ignored)',
       negatable: false,
       defaultsTo: false);
   parser.addMultiOption('category-order',
       help:
-          'A list of package names to place first when --display-as-packages is '
-          'set.  Unmentioned categories are sorted after these. (deprecated, replaced by package-order)',
+          'A list of package names to place first when grouping libraries in packages. '
+          'Unmentioned categories are sorted after these. (deprecated, replaced by package-order)',
       splitCommas: true);
   parser.addMultiOption('package-order',
       help:
-          'A list of package names to place first when --display-as-packages is '
-          'set.  Unmentioned categories are sorted after these.',
+          'A list of package names to place first when grouping libraries in packages. '
+          'Unmentioned categories are sorted after these.',
       splitCommas: true);
   parser.addFlag('auto-include-dependencies',
       help:

lib/dartdoc.dart

@@ -46,14 +46,12 @@ Future<List<Generator>> initGenerators(String url, String relCanonicalPrefix,
     List<String> footerFilePaths,
     List<String> footerTextFilePaths,
     String faviconPath,
-    bool displayAsPackages: false,
     bool prettyIndexJson: false}) async {
   var options = new HtmlGeneratorOptions(
       url: url,
       relCanonicalPrefix: relCanonicalPrefix,
       toolVersion: version,
       faviconPath: faviconPath,
-      displayAsPackages: displayAsPackages,
       prettyIndexJson: prettyIndexJson);
 
   return [

lib/resources/styles.css

@@ -630,6 +630,19 @@ ul.subnav li:last-of-type {
   padding-top: 25px;
 }
 
+.sidebar ol li.section-subtitle a {
+  color: inherit;
+}
+
+.sidebar ol li.section-subtitle {
+  font-weight: 400;
+  text-transform: uppercase;
+}
+
+.sidebar ol li.section-subitem {
+  margin-left: 12px;
+}
+
 .sidebar ol li:first-child {
   padding-top: 0;
   margin-top: 0;

lib/src/html/html_generator.dart

@@ -115,9 +115,6 @@ class HtmlGeneratorOptions implements HtmlOptions {
   final String faviconPath;
   final bool prettyIndexJson;
 
-  @override
-  final bool displayAsPackages;
-
   @override
   final String relCanonicalPrefix;
 
@@ -129,7 +126,6 @@ class HtmlGeneratorOptions implements HtmlOptions {
       this.relCanonicalPrefix,
       this.faviconPath,
       String toolVersion,
-      this.displayAsPackages: false,
       this.prettyIndexJson: false})
       : this.toolVersion = toolVersion ?? 'unknown';
 }

lib/src/html/template_data.dart

@@ -7,7 +7,6 @@ import '../model.dart';
 abstract class HtmlOptions {
   String get relCanonicalPrefix;
   String get toolVersion;
-  bool get displayAsPackages;
 }
 
 class Subnav {
@@ -63,7 +62,6 @@ abstract class TemplateData<T extends Documentable> {
   T get self;
   String get version => htmlOptions.toolVersion;
   String get relCanonicalPrefix => htmlOptions.relCanonicalPrefix;
-  bool get displayAsPackages => htmlOptions.displayAsPackages;
 
   Iterable<Subnav> getSubNavItems() => <Subnav>[];
 
@@ -113,7 +111,7 @@ class PackageTemplateData extends TemplateData<PackageGraph> {
   String get homepage => packageGraph.homepage;
 
   @override
-  String get kind => (displayAsPackages || packageGraph.isSdk) ? '' : 'package';
+  String get kind => packageGraph.kind;
 
   /// `null` for packages because they are at the root – not needed
   @override

lib/src/html/templates.dart

@@ -20,6 +20,8 @@ const _partials = const <String>[
   'constant',
   'footer',
   'head',
+  'library',
+  'packages',
   'property',
   'features',
   'documentation',