Merge pull request #1132 from dart-lang/headers

extend --include and --header

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 (`--include-external`)
+* [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,21 +68,24 @@ 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'];
+  List<String> includeExternals = args['include-external'];
 
   String url = args['hosted-url'];
-  String footerFilePath = _resolveTildePath(args['footer']);
-  if (footerFilePath != null && !new File(footerFilePath).existsSync()) {
-    print("Error: unable to locate the file with footer at ${footerFilePath}.");
-    exit(1);
+  List<String> footerFilePaths = args['footer'].map(_resolveTildePath).toList();
+  for (String footerFilePath in footerFilePaths) {
+    if (!new File(footerFilePath).existsSync()) {
+      print("Error: unable to locate footer file: ${footerFilePath}.");
+      exit(1);
+    }
   }
-  String headerFilePath = _resolveTildePath(args['header']);
-  if (headerFilePath != null && !new File(headerFilePath).existsSync()) {
-    print("Error: unable to locate the file with header at ${headerFilePath}.");
-    exit(1);
+  List<String> headerFilePaths = args['header'].map(_resolveTildePath).toList();
+  for (String headerFilePath in footerFilePaths) {
+    if (!new File(headerFilePath).existsSync()) {
+      print("Error: unable to locate header file: ${headerFilePath}.");
+      exit(1);
+    }
   }
 
   Directory outputDir =
@@ -112,7 +115,7 @@ main(List<String> arguments) async {
   print('');
 
   var generators = await initGenerators(
-      url, headerFilePath, footerFilePath, args['rel-canonical-prefix']);
+      url, headerFilePaths, footerFilePaths, args['rel-canonical-prefix']);
 
   for (var generator in generators) {
     generator.onFileCreated.listen(_onProgress);
@@ -124,7 +127,8 @@ main(List<String> arguments) async {
   initializeConfig(addCrossdart: addCrossdart, includeSource: includeSource);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
-      outputDir, packageMeta, includeLibraries);
+      outputDir, packageMeta, includeLibraries,
+      includeExternals: includeExternals);
 
   Chain.capture(() async {
     DartDocResults results = await dartdoc.generateDocs();
@@ -163,7 +167,7 @@ ArgParser _createArgsParser() {
   parser.addFlag('version',
       help: 'Display the version for $name.', negatable: false);
   parser.addFlag('add-crossdart',
-      help: 'Add Crossdart links to the source code pieces',
+      help: 'Add Crossdart links to the source code pieces.',
       negatable: false,
       defaultsTo: false);
   parser.addOption('dart-sdk',
@@ -181,26 +185,25 @@ ArgParser _createArgsParser() {
   parser.addOption('output',
       help: 'Path to output directory.', defaultsTo: defaultOutDir);
   parser.addOption('header',
-      help:
-          'path to file containing HTML text, inserted into the header of every page.');
+      allowMultiple: true, help: 'path to file containing HTML text.');
   parser.addOption('footer',
-      help:
-          'path to file containing HTML text, inserted into the footer of every page.');
+      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('include-external',
+      allowMultiple: true, help: 'additional (external) libraries to include');
   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. '
+      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');
+          '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';
@@ -44,13 +44,13 @@ const String version = '0.9.2';
 final String defaultOutDir = p.join('doc', 'api');
 
 /// Initialize and setup the generators.
-Future<List<Generator>> initGenerators(String url, String headerFilePath,
-    String footerFilePath, String relCanonicalPrefix) async {
+Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
+    List<String> footerFilePaths, String relCanonicalPrefix) async {
   return [
     await HtmlGenerator.create(
         url: url,
-        header: headerFilePath,
-        footer: footerFilePath,
+        headers: headerFilePaths,
+        footers: footerFilePaths,
         relCanonicalPrefix: relCanonicalPrefix,
         toolVersion: version)
   ];
@@ -60,17 +60,19 @@ Future<List<Generator>> initGenerators(String url, String headerFilePath,
 /// directory.
 class DartDoc {
   final Directory rootDir;
-  final List<String> excludes;
   final Directory sdkDir;
   final List<Generator> generators;
   final Directory outputDir;
   final PackageMeta packageMeta;
   final List<String> includes;
+  final List<String> includeExternals;
+  final List<String> excludes;
 
   Stopwatch _stopwatch;
 
   DartDoc(this.rootDir, this.excludes, this.sdkDir, this.generators,
-      this.outputDir, this.packageMeta, this.includes);
+      this.outputDir, this.packageMeta, this.includes,
+      {this.includeExternals: const []});
 
   /// Generate DartDoc documentation.
   ///
@@ -85,7 +87,7 @@ class DartDoc {
         ? const []
         : findFilesToDocumentInPackage(rootDir.path).toList();
 
-    List<LibraryElement> libraries = _parseLibraries(files);
+    List<LibraryElement> libraries = _parseLibraries(files, includeExternals);
 
     if (includes != null && includes.isNotEmpty) {
       Iterable knownLibraryNames = libraries.map((l) => l.name);
@@ -106,7 +108,7 @@ class DartDoc {
     }
 
     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 +133,8 @@ class DartDoc {
     return new DartDocResults(packageMeta, package, outputDir);
   }
 
-  List<LibraryElement> _parseLibraries(List<String> files) {
+  List<LibraryElement> _parseLibraries(
+      List<String> files, List<String> includeExternals) {
     Set<LibraryElement> libraries = new Set();
     DartSdk sdk = new DirectoryBasedDartSdk(new JavaFile(sdkDir.path));
     List<UriResolver> resolvers = [];
@@ -216,6 +219,14 @@ class DartDoc {
       result = context.performAnalysisTask();
     }
 
+    // Use the includeExternals.
+    for (Source source in context.librarySources) {
+      LibraryElement library = context.computeLibraryElement(source);
+      if (includeExternals.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/html_generator.dart

@@ -48,12 +48,12 @@ class HtmlGenerator extends Generator {
   /// [url] - optional URL for where the docs will be hosted.
   static Future<HtmlGenerator> create(
       {String url,
-      String header,
-      String footer,
+      List<String> headers,
+      List<String> footers,
       String relCanonicalPrefix,
       String toolVersion}) async {
     var templates =
-        await Templates.create(headerPath: header, footerPath: footer);
+        await Templates.create(headerPaths: headers, footerPaths: footers);
 
     if (toolVersion == null) {
       toolVersion = 'unknown';

lib/src/html/templates.dart

@@ -32,21 +32,31 @@ const _partials = const <String>[
 ];
 
 Future<Map<String, String>> _loadPartials(
-    String headerPath, String footerPath) async {
+    List<String> headerPaths, List<String> footerPaths) async {
+  headerPaths ??= [];
+  footerPaths ??= [];
+
   var partials = <String, String>{};
 
   Future<String> _loadPartial(String templatePath) async {
     String template = await _getTemplateFile(templatePath);
-    // TODO: revisit, not sure this is the right place for this logic
-    if (templatePath.contains('_footer') && footerPath != null) {
-      String footerValue = await new File(footerPath).readAsString();
+    if (templatePath.contains('_head') && headerPaths.isNotEmpty) {
+      String headerValue = headerPaths
+          .map((path) => new File(path).readAsStringSync())
+          .join('\n');
       template =
-          template.replaceAll('<!-- Footer Placeholder -->', footerValue);
+          template.replaceAll('<!-- Header Placeholder -->', headerValue);
+      template =
+          template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
     }
-    if (templatePath.contains('_head') && headerPath != null) {
-      String headerValue = await new File(headerPath).readAsString();
+    if (templatePath.contains('_footer') && footerPaths.isNotEmpty) {
+      String footerValue = footerPaths
+          .map((path) => new File(path).readAsStringSync())
+          .join('\n');
       template =
-          template.replaceAll('<!-- Header Placeholder -->', headerValue);
+          template.replaceAll('<!-- Footer Placeholder -->', footerValue);
+      template =
+          template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
     }
     return template;
   }
@@ -75,8 +85,8 @@ class Templates {
   final TemplateRenderer typeDefTemplate;
 
   static Future<Templates> create(
-      {String headerPath, String footerPath}) async {
-    var partials = await _loadPartials(headerPath, footerPath);
+      {List<String> headerPaths, List<String> footerPaths}) async {
+    var partials = await _loadPartials(headerPaths, footerPaths);
 
     String _partial(String name) {
       String partial = partials[name];

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;