support external --include s

Author: devoncarew

.gitignore

@@ -1,20 +1,21 @@
-# Don’t commit the following directories created by pub.
 build/
 doc/api/
 test_package/doc
 test_package_small/doc
 packages
 .buildlog
 .pub
+
 .idea
+.atom/
+
 .packages
 .settings/
 .DS_Store
 *.iml
 
 pub.dartlang.org/
 
-# Or the files created by dart2js.
 *.dart.js
 *.js.deps
 *.js.map

CHANGELOG.md

@@ -1,11 +1,16 @@
 ## 0.9.3
-* [enhancement] Added support for URL-based search. If a query parameter named
+* [enhancement] added support for URL-based search. If a query parameter named
   "search" is passed, the page navigates to the first search result for its
   value.
+* [enhancement] added support for passing more than one `--header` or `--footer`
+* [enhancement] added the ability to `--include` libraries referenced by (but
+  not directly inside) the project
+* [bug] rev the analyzer version used to fix an issue generating docs for
+  Flutter
 
 ## 0.9.2
 * [bug] do not generate docs for `dart:_internal` and `dart:nativewrappers`, when defined
-  in the `_embedder.yaml` file. 
+  in the `_embedder.yaml` file.
 * [enhancement] print message to run pub if dartdoc does not find any libraries to
   document.
 

bin/dartdoc.dart

@@ -9,8 +9,8 @@ import 'dart:io';
 import 'package:args/args.dart';
 import 'package:cli_util/cli_util.dart' as cli_util;
 import 'package:dartdoc/dartdoc.dart';
-import 'package:dartdoc/src/package_meta.dart';
 import 'package:dartdoc/src/config.dart';
+import 'package:dartdoc/src/package_meta.dart';
 import 'package:path/path.dart' as path;
 import 'package:stack_trace/stack_trace.dart';
 
@@ -68,22 +68,18 @@ main(List<String> arguments) async {
     exit(1);
   }
 
-  List<String> excludeLibraries =
-      args['exclude'] == null ? [] : args['exclude'].split(',');
-  List<String> includeLibraries =
-      args['include'] == null ? [] : args['include'].split(',');
+  List<String> excludeLibraries = args['exclude'];
+  List<String> includeLibraries = args['include'];
 
   String url = args['hosted-url'];
   List<String> footerFilePaths = args['footer'].map(_resolveTildePath).toList();
-  print(footerFilePaths);
   for (String footerFilePath in footerFilePaths) {
     if (!new File(footerFilePath).existsSync()) {
       print("Error: unable to locate footer file: ${footerFilePath}.");
       exit(1);
     }
   }
   List<String> headerFilePaths = args['header'].map(_resolveTildePath).toList();
-  print(headerFilePaths);
   for (String headerFilePath in footerFilePaths) {
     if (!new File(headerFilePath).existsSync()) {
       print("Error: unable to locate header file: ${headerFilePath}.");
@@ -187,26 +183,23 @@ ArgParser _createArgsParser() {
   parser.addOption('output',
       help: 'Path to output directory.', defaultsTo: defaultOutDir);
   parser.addOption('header',
-      allowMultiple: true,
-      help: 'path to file containing HTML text.');
+      allowMultiple: true, help: 'path to file containing HTML text.');
   parser.addOption('footer',
-      allowMultiple: true,
-      help: 'path to file containing HTML text.');
+      allowMultiple: true, help: 'path to file containing HTML text.');
   parser.addOption('exclude',
-      help: 'Comma-separated list of library names to ignore.');
+      allowMultiple: true, help: 'library names to ignore');
   parser.addOption('include',
-      help: 'Comma-separated list of library names to generate docs for.');
+      allowMultiple: true, help: 'library names to generate docs for');
   parser.addOption('hosted-url',
       help:
           'URL where the docs will be hosted (used to generate the sitemap).');
   parser.addOption('rel-canonical-prefix',
-      help: 'If provided, add a rel="canonical" prefixed with provided value. \n'
+      help:
+          'If provided, add a rel="canonical" prefixed with provided value. \n'
           'Consider using if building many versions of the docs for public SEO. '
           'Learn more at https://goo.gl/gktN6F.');
   parser.addFlag('include-source',
-      help: 'If source code blocks should be shown, if they exist.',
-      negatable: true,
-      defaultsTo: true);
+      help: 'Show source code blocks', negatable: true, defaultsTo: true);
   return parser;
 }
 

lib/dartdoc.dart

@@ -15,7 +15,7 @@ import 'package:analyzer/source/package_map_provider.dart';
 import 'package:analyzer/source/package_map_resolver.dart';
 import 'package:analyzer/source/pub_package_map_provider.dart';
 import 'package:analyzer/source/sdk_ext.dart';
-import 'package:analyzer/src/generated/element.dart';
+import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/error.dart';
 import 'package:analyzer/src/generated/java_io.dart';
@@ -85,28 +85,17 @@ class DartDoc {
         ? const []
         : findFilesToDocumentInPackage(rootDir.path).toList();
 
-    List<LibraryElement> libraries = _parseLibraries(files);
+    List<LibraryElement> libraries = _parseLibraries(files, includes);
 
-    if (includes != null && includes.isNotEmpty) {
-      Iterable knownLibraryNames = libraries.map((l) => l.name);
-      Set notFound =
-          new Set.from(includes).difference(new Set.from(knownLibraryNames));
-      if (notFound.isNotEmpty) {
-        throw 'Did not find: [${notFound.join(', ')}] in '
-            'known libraries: [${knownLibraryNames.join(', ')}]';
-      }
-      libraries.removeWhere((lib) => !includes.contains(lib.name));
-    } else {
-      // remove excluded libraries
-      excludes.forEach((pattern) {
-        libraries.removeWhere((lib) {
-          return lib.name.startsWith(pattern) || lib.name == pattern;
-        });
+    // remove excluded libraries
+    excludes.forEach((pattern) {
+      libraries.removeWhere((lib) {
+        return lib.name.startsWith(pattern) || lib.name == pattern;
       });
-    }
+    });
 
     if (includes.isNotEmpty || excludes.isNotEmpty) {
-      print('Generating docs for libraries ${libraries.join(', ')}\n');
+      print('generating docs for libraries ${libraries.join(', ')}\n');
     }
 
     Package package = new Package(libraries, packageMeta);
@@ -131,7 +120,8 @@ class DartDoc {
     return new DartDocResults(packageMeta, package, outputDir);
   }
 
-  List<LibraryElement> _parseLibraries(List<String> files) {
+  List<LibraryElement> _parseLibraries(
+      List<String> files, List<String> includes) {
     Set<LibraryElement> libraries = new Set();
     DartSdk sdk = new DirectoryBasedDartSdk(new JavaFile(sdkDir.path));
     List<UriResolver> resolvers = [];
@@ -216,6 +206,14 @@ class DartDoc {
       result = context.performAnalysisTask();
     }
 
+    // Use the includes.
+    for (Source source in context.librarySources) {
+      LibraryElement library = context.computeLibraryElement(source);
+      if (includes.contains(Library.getLibraryName(library))) {
+        libraries.add(library);
+      }
+    }
+
     List<AnalysisErrorInfo> errorInfos = [];
 
     for (Source source in sources) {

lib/src/element_type.dart

@@ -5,6 +5,7 @@
 /// The models used to represent Dart code.
 library dartdoc.element_type;
 
+import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/src/generated/element.dart';
 
 import 'model.dart';

lib/src/html/templates.dart

@@ -41,16 +41,23 @@ Future<Map<String, String>> _loadPartials(
   Future<String> _loadPartial(String templatePath) async {
     String template = await _getTemplateFile(templatePath);
     if (templatePath.contains('_head') && headerPaths.isNotEmpty) {
-      String headerValue = headerPaths.map((path) => new File(path).readAsStringSync()).join('\n');
+      String headerValue = headerPaths
+          .map((path) => new File(path).readAsStringSync())
+          .join('\n');
       template =
           template.replaceAll('<!-- Header Placeholder -->', headerValue);
+      template =
+          template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
     }
     if (templatePath.contains('_footer') && footerPaths.isNotEmpty) {
-      String footerValue = footerPaths.map((path) => new File(path).readAsStringSync()).join('\n');
+      String footerValue = footerPaths
+          .map((path) => new File(path).readAsStringSync())
+          .join('\n');
       template =
           template.replaceAll('<!-- Footer Placeholder -->', footerValue);
+      template =
+          template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
     }
-    template = template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
     return template;
   }
 

lib/src/markdown_processor.dart

@@ -8,7 +8,7 @@ library dartdoc.markdown_processor;
 
 import 'dart:convert';
 
-import 'package:analyzer/src/generated/ast.dart';
+import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/src/generated/element.dart'
     show
         LibraryElement,

lib/src/model.dart

@@ -7,7 +7,7 @@ library dartdoc.models;
 
 import 'dart:convert';
 
-import 'package:analyzer/src/generated/ast.dart'
+import 'package:analyzer/dart/ast/ast.dart'
     show AnnotatedNode, Annotation, Declaration;
 import 'package:analyzer/src/generated/element.dart';
 import 'package:analyzer/src/generated/resolver.dart'
@@ -902,6 +902,17 @@ abstract class GetterSetterCombo {
 class Library extends ModelElement {
   static final Map<String, Library> _libraryMap = <String, Library>{};
 
+  static String getLibraryName(LibraryElement element) {
+    String name = element.name;
+
+    if (name == null || name.isEmpty) {
+      name = element.definingCompilationUnit.name;
+      name = name.substring(0, name.length - '.dart'.length);
+    }
+
+    return name;
+  }
+
   final Package package;
   List<Class> _classes;
   List<Class> _enums;