implement a --use-categories option

Author: devoncarew

CHANGELOG.md

@@ -1,6 +1,8 @@
 ## unreleased
 * [enhancement] added a `--favicon` option to specify a favicon to use for the
   generated docs
+* [enhancement] added a `--use-categories` flag to groups libraries into source
+  packages in the overview page and the left-hand side navigation panel
 
 ## 0.9.3+1
 * [bug] fix an issue with including duplicated libraries

bin/dartdoc.dart

@@ -116,7 +116,7 @@ main(List<String> arguments) async {
 
   var generators = await initGenerators(
       url, headerFilePaths, footerFilePaths, args['rel-canonical-prefix'],
-      faviconPath: args['favicon']);
+      faviconPath: args['favicon'], useCategories: args['use-categories']);
 
   for (var generator in generators) {
     generator.onFileCreated.listen(_onProgress);
@@ -207,6 +207,10 @@ ArgParser _createArgsParser() {
       help: 'Show source code blocks', negatable: true, defaultsTo: true);
   parser.addOption('favicon',
       help: 'A path to a favicon for the generated docs');
+  parser.addFlag('use-categories',
+      help: 'Group libraries from the same package into categories',
+      negatable: false,
+      defaultsTo: false);
   return parser;
 }
 

lib/dartdoc.dart

@@ -46,15 +46,16 @@ final String defaultOutDir = p.join('doc', 'api');
 /// Initialize and setup the generators.
 Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
     List<String> footerFilePaths, String relCanonicalPrefix,
-    {String faviconPath}) async {
+    {String faviconPath, bool useCategories: false}) async {
   return [
     await HtmlGenerator.create(
         url: url,
         headers: headerFilePaths,
         footers: footerFilePaths,
         relCanonicalPrefix: relCanonicalPrefix,
         toolVersion: version,
-        faviconPath: faviconPath)
+        faviconPath: faviconPath,
+        useCategories: useCategories)
   ];
 }
 

lib/src/html/html_generator.dart

@@ -40,6 +40,7 @@ class HtmlGenerator extends Generator {
   final Templates _templates;
   final String _toolVersion;
   final String faviconPath;
+  final bool useCategories;
 
   final StreamController<File> _onFileCreated =
       new StreamController(sync: true);
@@ -53,7 +54,8 @@ class HtmlGenerator extends Generator {
       List<String> footers,
       String relCanonicalPrefix,
       String toolVersion,
-      String faviconPath}) async {
+      String faviconPath,
+      bool useCategories: false}) async {
     var templates =
         await Templates.create(headerPaths: headers, footerPaths: footers);
 
@@ -62,17 +64,17 @@ class HtmlGenerator extends Generator {
     }
 
     return new HtmlGenerator._(url, relCanonicalPrefix, templates, toolVersion,
-        faviconPath: faviconPath);
+        faviconPath: faviconPath, useCategories: useCategories);
   }
 
   HtmlGenerator._(
       this._url, this._relCanonicalPrefix, this._templates, this._toolVersion,
-      {this.faviconPath});
+      {this.faviconPath, this.useCategories});
 
   Future generate(Package package, Directory out) {
     return new HtmlGeneratorInstance(_toolVersion, _url, _templates, package,
             out, _onFileCreated, _relCanonicalPrefix,
-            faviconPath: faviconPath)
+            faviconPath: faviconPath, useCategories: useCategories)
         .generate();
   }
 }

lib/src/html/html_generator_instance.dart

@@ -25,10 +25,11 @@ class HtmlGeneratorInstance implements HtmlOptions {
   final String relCanonicalPrefix;
   final String toolVersion;
   final String faviconPath;
+  final bool useCategories;
 
   HtmlGeneratorInstance(this.toolVersion, this.url, this._templates,
       this.package, this.out, this._onFileCreated, this.relCanonicalPrefix,
-      {this.faviconPath});
+      {this.faviconPath, this.useCategories});
 
   Future generate() async {
     if (!out.existsSync()) out.createSync();
@@ -134,7 +135,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
   void generatePackage() {
     stdout.write('documenting ${package.name}');
 
-    TemplateData data = new PackageTemplateData(this, package);
+    TemplateData data = new PackageTemplateData(this, package, useCategories);
 
     _build('index.html', _templates.indexTemplate, data);
   }
@@ -148,7 +149,8 @@ class HtmlGeneratorInstance implements HtmlOptions {
           "documentation comments");
     }
 
-    TemplateData data = new LibraryTemplateData(this, package, lib);
+    TemplateData data =
+        new LibraryTemplateData(this, package, lib, useCategories);
 
     _build(path.join(lib.dirName, '${lib.fileName}'),
         _templates.libraryTemplate, data);

lib/src/html/template_data.dart

@@ -68,10 +68,12 @@ abstract class TemplateData<T extends Documentable> {
 }
 
 class PackageTemplateData extends TemplateData<Package> {
-  PackageTemplateData(HtmlOptions htmlOptions, Package package)
+  PackageTemplateData(
+      HtmlOptions htmlOptions, Package package, this.useCategories)
       : super(htmlOptions, package);
 
   bool get includeVersion => true;
+  final bool useCategories;
   List get navLinks => [];
   String get title => '${package.name} - Dart API docs';
   Package get self => package;
@@ -90,11 +92,13 @@ class PackageTemplateData extends TemplateData<Package> {
 class LibraryTemplateData extends TemplateData<Library> {
   final Library library;
 
-  LibraryTemplateData(HtmlOptions htmlOptions, Package package, this.library)
+  LibraryTemplateData(HtmlOptions htmlOptions, Package package, this.library,
+      this.useCategories)
       : super(htmlOptions, package);
 
   String get title => '${library.name} library - Dart API';
   String get documentation => library.documentation;
+  final bool useCategories;
   String get htmlBase => '..';
   String get metaDescription =>
       '${library.name} library API docs, for the Dart programming language.';

lib/src/model.dart

@@ -6,6 +6,7 @@
 library dartdoc.models;
 
 import 'dart:convert';
+import 'dart:io';
 
 import 'package:analyzer/dart/ast/ast.dart'
     show AnnotatedNode, Annotation, Declaration;
@@ -16,6 +17,7 @@ import 'package:analyzer/src/generated/resolver.dart'
 import 'package:analyzer/src/generated/source_io.dart';
 import 'package:analyzer/src/generated/utilities_dart.dart' show ParameterKind;
 import 'package:collection/collection.dart';
+import 'package:path/path.dart' as p;
 import 'package:quiver/core.dart' show hash3;
 
 import 'config.dart';
@@ -921,6 +923,7 @@ class Library extends ModelElement {
   List<TopLevelVariable> _variables;
   Namespace _exportedNamespace;
   String _name;
+  String _packageName;
 
   factory Library(LibraryElement element, Package package) {
     String key = element == null ? 'null' : element.name;
@@ -1020,6 +1023,21 @@ class Library extends ModelElement {
   @override
   String get href => '$dirName/$fileName';
 
+  String get packageName {
+    if (_packageName == null) {
+      String sourcePath = _library.source.fullName;
+      File file = new File(sourcePath);
+      if (file.existsSync()) {
+        _packageName = _getPackageName(file.parent);
+        if (_packageName == null) _packageName = '';
+      } else {
+        _packageName = '';
+      }
+    }
+
+    return _packageName;
+  }
+
   bool get isAnonymous => element.name == null || element.name.isEmpty;
 
   bool get isDocumented => oneLineDoc.isNotEmpty;
@@ -1143,6 +1161,20 @@ class Library extends ModelElement {
 
     return _variables;
   }
+
+  static String _getPackageName(Directory dir) {
+    if (!dir.existsSync() || !dir.path.contains(Platform.pathSeparator)) {
+      return null;
+    }
+
+    File pubspec = new File(p.join(dir.path, 'pubspec.yaml'));
+    if (pubspec.existsSync()) {
+      PackageMeta meta = new PackageMeta.fromDir(dir);
+      return meta.name;
+    } else {
+      return _getPackageName(dir.parent);
+    }
+  }
 }
 
 class Method extends ModelElement
@@ -1718,6 +1750,25 @@ class Package implements Nameable, Documentable {
 
   List<Library> get libraries => _libraries;
 
+  List<PackageCategory> get categories {
+    Map<String, PackageCategory> result = {};
+
+    for (Library library in _libraries) {
+      String name = '';
+
+      if (library.name.startsWith('dart:')) {
+        name = 'Dart Core';
+      } else {
+        name = library.packageName;
+      }
+
+      if (!result.containsKey(name)) result[name] = new PackageCategory(name);
+      result[name]._libraries.add(library);
+    }
+
+    return result.values.toList()..sort();
+  }
+
   String get name => packageMeta.name;
 
   String get oneLineDoc => '';
@@ -1780,6 +1831,17 @@ class Package implements Nameable, Documentable {
   }
 }
 
+class PackageCategory implements Comparable {
+  final String name;
+  final List<Library> _libraries = [];
+
+  PackageCategory(this.name);
+
+  List<Library> get libraries => _libraries;
+
+  int compareTo(PackageCategory other) => name.compareTo(other.name);
+}
+
 class Parameter extends ModelElement implements EnclosedElement {
   Parameter(ParameterElement element, Library library)
       : super(element, library) {

lib/templates/index.html

@@ -3,38 +3,67 @@
   <div class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
     <h5>{{self.name}}</h5>
 
+    {{#useCategories}}
+    <ol>
+      {{#package.categories}}
+        <li class="section-title">{{name}}</li>
+        {{#libraries}}
+        <li>{{{linkedName}}}</li>
+        {{/libraries}}
+      {{/package.categories}}
+
+    </ol>
+    {{/useCategories}}
+
+    {{^useCategories}}
     <ol>
       <li class="section-title"><a href="{{package.href}}#libraries">Libraries</a></li>
       {{#package.libraries}}
       <li>{{{linkedName}}}</li>
       {{/package.libraries}}
     </ol>
+    {{/useCategories}}
   </div>
 
   <div class="col-xs-12 col-sm-9 col-md-8 main-content">
-
     {{#package}}
       {{>documentation}}
     {{/package}}
 
-    <section class="summary" id="libraries">
-      <h2>Libraries</h2>
-      <dl>
-        {{#package.libraries}}
-          <dt id="{{htmlId}}">
-            <span class="name">{{{ linkedName }}}</span>
-          </dt>
-          <dd>
-            {{#isDocumented}}
-            <p>
-              {{{ oneLineDoc }}}
-              {{>has_more_docs}}
-            </p>
-            {{/isDocumented}}
-          </dd>
-        {{/package.libraries}}
-      </dl>
-    </section>
+    {{#useCategories}}
+      {{#package.categories}}
+        <section class="summary">
+          <h2>{{name}}</h2>
+          <dl>
+            {{#libraries}}
+              <dt id="{{htmlId}}">
+                <span class="name">{{{ linkedName }}}</span>
+              </dt>
+              <dd>
+                {{#isDocumented}}<p>{{{ oneLineDoc }}}</p>{{/isDocumented}}
+              </dd>
+            {{/libraries}}
+          </dl>
+        </section>
+      {{/package.categories}}
+
+    {{/useCategories}}
+
+    {{^useCategories}}
+      <section class="summary" id="libraries">
+        <h2>Libraries</h2>
+        <dl>
+          {{#package.libraries}}
+            <dt id="{{htmlId}}">
+              <span class="name">{{{ linkedName }}}</span>
+            </dt>
+            <dd>
+              {{#isDocumented}}<p>{{{ oneLineDoc }}}</p>{{/isDocumented}}
+            </dd>
+          {{/package.libraries}}
+        </dl>
+      </section>
+    {{/useCategories}}
 
   </div> <!-- /.main-content -->
 

lib/templates/library.html

@@ -5,12 +5,26 @@
     <h5><a href="{{href}}">{{name}}</a></h5>
     {{/navLinks}}
 
+    {{#useCategories}}
     <ol>
-      <li class="section-title"><a href="index.html">Libraries</a></li>
+      {{#package.categories}}
+        <li class="section-title">{{name}}</li>
+        {{#libraries}}
+        <li>{{{linkedName}}}</li>
+        {{/libraries}}
+      {{/package.categories}}
+
+    </ol>
+    {{/useCategories}}
+
+    {{^useCategories}}
+    <ol>
+      <li class="section-title"><a href="{{package.href}}#libraries">Libraries</a></li>
       {{#package.libraries}}
       <li>{{{linkedName}}}</li>
       {{/package.libraries}}
     </ol>
+    {{/useCategories}}
   </div>
 
   <div class="col-xs-12 col-sm-9 col-md-8 main-content">

test/model_test.dart

@@ -47,6 +47,14 @@ void main() {
         expect(package.libraries, hasLength(6));
       });
 
+      test('categories', () {
+        expect(package.categories, hasLength(1));
+
+        PackageCategory category = package.categories.first;
+        expect(category.name, 'test_package');
+        expect(category.libraries, hasLength(6));
+      });
+
       test('is documented in library', () {
         expect(package.isDocumented(exLibrary.element), isTrue);
       });
@@ -121,6 +129,10 @@ void main() {
       expect(exLibrary.name, 'ex');
     });
 
+    test('packageName', () {
+      expect(exLibrary.packageName, 'test_package');
+    });
+
     test('has a fully qualified name', () {
       expect(exLibrary.fullyQualifiedName, 'ex');
     });