Expand category system to all top level items (#1754)

* Flatten non-doc changes

* Rebuild test package docs

* Update changelog to pass test

* Review comments

* Rename APIs to Topics

* Rebuild test package docs

Author: jcollins-g

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.21.0-dev.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
+  is replaced with a more generic "categories" option.  See README.md.
+
 ## 0.20.4
 * Hide pragma declarations from generated docs (#1726)
 * Fix problems with lists in markdown not being handled correctly (#172)

README.md

@@ -102,15 +102,22 @@ generates docs.
 
 ```yaml
 dartdoc:
-  categoryOrder: ["First Category", "Second Category"]
+  categories: 
+    "First Category":
+      markdown: doc/First.md
+      name: Awesome
+    "Second Category":
+      markdown: doc/Second.md
+      name: Great
   linkTo:
     url: "https://my.dartdocumentationsite.org/dev/%v%"
 ```
 
 Unrecognized options will be ignored.  Supported options:
 
-  * **categoryOrder**:  Specify the order of categories, below, for display in the sidebar and
-    the package page.
+  * **categories**:  Specify the order of categories.  For APIs 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:'.
   * **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.
@@ -144,9 +151,11 @@ as POSIX paths.  Dartdoc will convert POSIX paths automatically on Windows.
 
 ### 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.
+You can tag libraries or top level classes, functions, and variables in their documentation with
+the string `{@category YourCategory}`.  For libraries, that will cause the library to appear in a
+category when showing the sidebar on the Package and Library pages.  For other types of objects,
+the `{@category}` will be shown with a link to the category page if specified in
+dartdoc_options.yaml, as above.
 
 ```dart
 /// Here is my library.
@@ -155,6 +164,42 @@ and Library pages.
 library my_library;
 ```
 
+#### Other category tags and categories.json
+
+A file `categories.json` will be generated at the top level of the documentation tree with
+information about categories collected from objects in the source tree.  The directives
+`@category`, `@subCategory`, `@image`, and `@samples` are understood and saved into this json.
+Future versions of dartdoc may make direct use of the image and samples tags.
+
+As an example, if we document the class Icon in flutter using the following:
+
+```dart
+/// {@category Basics}
+/// {@category Assets, Images, and Icons}
+/// {@subCategory Information displays}
+/// {@image <image alt='' src='/images/catalog-widget-placeholder.png'>}
+class Icon extends StatelessWidget {}
+```
+
+that will result in the following json:
+
+```json
+  {
+    "name": "Icon",
+    "qualifiedName": "widgets.Icon",
+    "href": "widgets/Icon-class.html",
+    "type": "class",
+    "categories": [
+      "Assets, Images, and Icons",
+      "Basics"
+    ],
+    "subcategories": [
+      "Information displays"
+    ],
+    "image": "<image alt='' src='/images/catalog-widget-placeholder.png'>"
+  }
+```
+
 ### Animations
 
 You can specify links to videos inline that will be handled with a simple HTML5 player:

analysis_options.yaml

@@ -11,6 +11,7 @@ analyzer:
     - 'testing/test_package_export_error/**'
 linter:
   rules:
+    - always_declare_return_types
     - annotate_overrides
     - avoid_init_to_null
     - directives_ordering

bin/dartdoc.dart

@@ -33,7 +33,7 @@ Future<List<DartdocOption>> createDartdocProgramOptions() async {
 
 /// Analyzes Dart files and generates a representation of included libraries,
 /// classes, and members. Uses the current directory to look for libraries.
-main(List<String> arguments) async {
+void main(List<String> arguments) async {
   DartdocOptionSet optionSet =
       await DartdocOptionSet.fromOptionGenerators('dartdoc', [
     createDartdocOptions,

lib/dartdoc.dart

@@ -66,7 +66,8 @@ class Dartdoc extends PackageBuilder {
 
   /// An asynchronous factory method that builds Dartdoc's file writers
   /// and returns a Dartdoc object with them.
-  static withDefaultGenerators(DartdocGeneratorOptionContext config) async {
+  static Future<Dartdoc> withDefaultGenerators(
+      DartdocGeneratorOptionContext config) async {
     List<Generator> generators = await initGenerators(config);
     return new Dartdoc._(config, generators);
   }
@@ -259,7 +260,7 @@ class Dartdoc extends PackageBuilder {
       } else {
         // Error messages are orphaned by design and do not appear in the search
         // index.
-        if (relativeFullPath != '__404error.html') {
+        if (<String>['__404error.html', 'categories.json'].contains(fullPath)) {
           _warn(packageGraph, PackageWarning.orphanedFile, fullPath,
               normalOrigin);
         }

lib/resources/styles.css

@@ -394,6 +394,55 @@ dl dt.callable .name {
   text-decoration: line-through;
 }
 
+.category.linked {
+  font-weight: bold;
+  opacity: 1;
+}
+
+/* Colors for category based on categoryOrder in dartdoc_options.config. */
+.category.cp-0 {
+  background-color: #54b7c4
+}
+
+.category.cp-1 {
+  background-color: #54c47f
+}
+
+.category.cp-2 {
+  background-color: #c4c254
+}
+
+.category.cp-3 {
+  background-color: #c49f54
+}
+
+.category.cp-4 {
+  background-color: #c45465
+}
+
+.category.cp-5 {
+  background-color: #c454c4
+}
+
+.category a {
+  color: white;
+}
+
+.category {
+  vertical-align: text-top;
+  padding: 4px;
+  font-size: 12px;
+  border-radius: 4px;
+  background-color: #B6B6B6;
+  text-transform: uppercase;
+  color: white;
+  opacity: .5;
+}
+
+h1 .category {
+  vertical-align: middle;
+}
+
 p.firstline {
   font-weight: bold;
 }