Document arbitrary SDK-like things as Dart SDKs. (#1665)

* refactors

* Library/Package/PackageGraph constructor shuffle

* Not quite there; still need to populate non-local packages

* weird vm thing

* Got it?

* Add another test

* tweaks for Flutter

* Initialization speedups

* Canonicalize path comparisons and increase timeouts on the complex dartdoc tests for travis

* Update grind with different parameters

* First step complete, now to eliminate dupes

* Condense more into config

* remove commented out line

* Everything but the generator information is moved now.

* dartfmt

* Restore a commented out test

* Use localPublicLibraries in restored test

* Move generator into DartDoc pseudo-factory

* Specify SDK dirs on command line

* dartfmt + review comments

* dartfmt

* pubspec

* Throw correct exception

* new is not optional yet

* Tweak to make cwd == SDK viable

* tweak travis timeout and fix windows

* Review comments

Author: jcollins-g

bin/dartdoc.dart

@@ -43,8 +43,8 @@ main(List<String> arguments) async {
     exit(0);
   }
 
-  Directory sdkDir = getSdkDir();
-  final bool sdkDocs = args['sdk-docs'];
+  Directory sdkDir = new Directory(args['sdk-dir']);
+  bool sdkDocs = args['sdk-docs'];
   final bool showProgress = args['show-progress'];
 
   Directory inputDir;
@@ -56,6 +56,14 @@ main(List<String> arguments) async {
     inputDir = args['input'];
   }
 
+  // If our input directory looks like the Dart SDK, then assume it is one,
+  // and is the one we want to document against.
+  PackageMeta packageMeta = new PackageMeta.fromDir(inputDir);
+  if (packageMeta.isSdk) {
+    sdkDir = inputDir;
+    sdkDocs = true;
+  }
+
   List<String> footerTextFilePaths = [];
   // If we're generating docs for the Dart SDK, we insert a copyright footer.
   if (sdkDocs) {
@@ -142,8 +150,6 @@ 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');
@@ -249,104 +255,108 @@ main(List<String> arguments) async {
 
 ArgParser _createArgsParser() {
   var parser = new ArgParser();
-  parser.addFlag('help',
-      abbr: 'h', negatable: false, help: 'Show command help.');
-  parser.addFlag('version',
-      help: 'Display the version for $name.', negatable: false);
   parser.addFlag('add-crossdart',
       help: 'Add Crossdart links to the source code pieces.',
       negatable: false,
       defaultsTo: false);
-  parser.addFlag('sdk-docs',
-      help: 'Generate ONLY the docs for the Dart SDK.', negatable: false);
-  parser.addFlag('show-warnings',
-      help: 'Display warnings.', negatable: false, defaultsTo: false);
-  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.');
-  parser.addOption('output',
-      help: 'Path to output directory.', defaultsTo: defaultOutDir);
-  parser.addMultiOption('header',
-      splitCommas: true, help: 'paths to header files containing HTML text.');
+  parser.addOption('ambiguous-reexport-scorer-min-confidence',
+      help:
+          'Minimum scorer confidence to suppress warning on ambiguous reexport.',
+      defaultsTo: '0.1',
+      hide: true);
+  parser.addFlag('auto-include-dependencies',
+      help:
+          'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',
+      negatable: false,
+      defaultsTo: false);
+  parser.addMultiOption('category-order',
+      help:
+          '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.addOption('example-path-prefix',
+      help: 'Prefix for @example paths.\n(defaults to the project root)');
+  parser.addMultiOption('exclude',
+      splitCommas: true, help: 'Library names to ignore.');
+  parser.addMultiOption('exclude-packages',
+      splitCommas: true, help: 'Package names to ignore.');
+  parser.addOption('favicon',
+      help: 'A path to a favicon for the generated docs.');
   parser.addMultiOption('footer',
       splitCommas: true, help: 'paths to footer files containing HTML text.');
   parser.addMultiOption('footer-text',
       splitCommas: true,
       help: 'paths to footer-text files '
           '(optional text next to the package name and version).');
-  parser.addMultiOption('exclude',
-      splitCommas: true, help: 'Library names to ignore.');
-  parser.addMultiOption('exclude-packages',
-      splitCommas: true, help: 'Package names to ignore.');
+  parser.addMultiOption('header',
+      splitCommas: true, help: 'paths to header files containing HTML text.');
+  parser.addFlag('help',
+      abbr: 'h', negatable: false, help: 'Show command help.');
+  parser.addFlag('hide-sdk-text',
+      help:
+          'Drop all text for SDK components.  Helpful for integration tests for dartdoc, probably not useful for anything else.',
+      negatable: true,
+      defaultsTo: false,
+      hide: true);
+  parser.addOption('hosted-url',
+      help:
+          'URL where the docs will be hosted (used to generate the sitemap).');
   parser.addMultiOption('include',
       splitCommas: true, help: 'Library names to generate docs for.');
   parser.addMultiOption('include-external',
       help: 'Additional (external) dart files to include; use "dir/fileName", '
           'as in lib/material.dart.');
-  parser.addOption('hosted-url',
-      help:
-          'URL where the docs will be hosted (used to generate the sitemap).');
-  parser.addOption('example-path-prefix',
-      help: 'Prefix for @example paths.\n(defaults to the project root)');
-  parser.addOption('rel-canonical-prefix',
-      help: 'If provided, add a rel="canonical" prefixed with provided value. '
-          'Consider using if\nbuilding many versions of the docs for public '
-          'SEO; learn more at https://goo.gl/gktN6F.');
   parser.addFlag('include-source',
       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 in the libraries sidebar. (deprecated, ignored)',
-      negatable: false,
-      defaultsTo: false);
-  parser.addMultiOption('category-order',
-      help:
-          '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.addOption('input', help: 'Path to source directory.');
+  parser.addFlag('json',
+      help: 'Prints out progress JSON maps. One entry per line.',
+      defaultsTo: false,
+      negatable: true);
+  parser.addOption('output',
+      help: 'Path to output directory.', defaultsTo: defaultOutDir);
   parser.addMultiOption('package-order',
       help:
           '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:
-          'Include all the used libraries into the docs, even the ones not in the current package or "include-external"',
-      negatable: false,
-      defaultsTo: false);
   parser.addFlag('pretty-index-json',
       help:
           "Generates `index.json` with indentation and newlines. The file is larger, but it's also easier to diff.",
       negatable: false,
       defaultsTo: false);
-  parser.addOption('ambiguous-reexport-scorer-min-confidence',
-      help:
-          'Minimum scorer confidence to suppress warning on ambiguous reexport.',
-      defaultsTo: "0.1",
-      hide: true);
-  parser.addFlag('verbose-warnings',
-      help: 'Display extra debugging information and help with warnings.',
-      negatable: true,
-      defaultsTo: true);
-  parser.addFlag('hide-sdk-text',
+  parser.addOption('rel-canonical-prefix',
+      help: 'If provided, add a rel="canonical" prefixed with provided value. '
+          'Consider using if\nbuilding many versions of the docs for public '
+          'SEO; learn more at https://goo.gl/gktN6F.');
+  parser.addFlag('sdk-docs',
+      help: 'Generate ONLY the docs for the Dart SDK.', negatable: false);
+  parser.addOption('sdk-readme',
+      help: 'Path to the SDK description file.  Deprecated (ignored)');
+  parser.addOption('sdk-dir',
+      help: 'Path to the SDK directory',
+      defaultsTo: defaultSdkDir.absolute.path);
+  parser.addFlag('show-warnings',
+      help: 'Display warnings.', negatable: false, defaultsTo: false);
+  parser.addFlag('show-progress',
+      help: 'Display progress indications to console stdout', negatable: false);
+  parser.addFlag('use-categories',
       help:
-          "Drop all text for SDK components.  Helpful for integration tests for dartdoc, probably not useful for anything else.",
-      negatable: true,
-      defaultsTo: false,
-      hide: true);
-  parser.addFlag('json',
-      help: 'Prints out progress JSON maps. One entry per line.',
-      defaultsTo: false,
-      negatable: true);
+          'Group libraries from the same package in the libraries sidebar. (deprecated, ignored)',
+      negatable: false,
+      defaultsTo: false);
   parser.addFlag('validate-links',
       help:
           'Runs the built-in link checker to display Dart context aware warnings for broken links (slow)',
       negatable: true,
       defaultsTo: true);
+  parser.addFlag('verbose-warnings',
+      help: 'Display extra debugging information and help with warnings.',
+      negatable: true,
+      defaultsTo: true);
+  parser.addFlag('version',
+      help: 'Display the version for $name.', negatable: false);
+
   return parser;
 }
 

lib/dartdoc.dart

@@ -32,7 +32,6 @@ export 'src/element_type.dart';
 export 'src/generator.dart';
 export 'src/model.dart';
 export 'src/package_meta.dart';
-export 'src/sdk.dart';
 
 const String name = 'dartdoc';
 // Update when pubspec version changes.

lib/src/config.dart

@@ -6,12 +6,9 @@ library dartdoc.config;
 
 import 'dart:io';
 
-import 'package:analyzer/dart/element/element.dart';
 import 'package:dartdoc/dartdoc.dart';
 import 'package:path/path.dart' as pathLib;
 
-import 'model.dart';
-
 String _resolveTildePath(String originalPath) {
   if (originalPath == null || !originalPath.startsWith('~/')) {
     return originalPath;
@@ -28,18 +25,6 @@ String _resolveTildePath(String originalPath) {
   return pathLib.join(homeDir, originalPath.substring(2));
 }
 
-/// Class representing values possibly local to a particular [ModelElement].
-class LocalConfig {
-  final Map<String, Set<String>> categoryMap;
-  final PackageMeta packageMeta;
-
-  LocalConfig._(this.categoryMap, this.packageMeta);
-
-  factory LocalConfig.fromLibrary(LibraryElement element) {
-    return new LocalConfig._({}, new PackageMeta.fromElement(element));
-  }
-}
-
 class DartDocConfig {
   final bool addCrossdart;
   final bool autoIncludeDependencies;
@@ -167,7 +152,7 @@ class DartDocConfig {
       prettyIndexJson,
       reexportMinConfidence,
       relCanonicalPrefix,
-      sdkDir ?? getSdkDir(),
+      sdkDir ?? defaultSdkDir,
       sdkVersion,
       showWarnings,
       validateLinks,

lib/src/model.dart

@@ -2048,7 +2048,7 @@ class Library extends ModelElement with Categorization {
   PackageMeta _packageMeta;
   PackageMeta get packageMeta {
     if (_packageMeta == null) {
-      _packageMeta = new PackageMeta.fromElement(element);
+      _packageMeta = new PackageMeta.fromElement(element, config);
     }
     return _packageMeta;
   }
@@ -3768,7 +3768,7 @@ class PackageGraph extends Canonicalization
 
     // Build [Library] objects, and link them to [Package]s.
     libraryElements.forEach((element) {
-      var packageMeta = new PackageMeta.fromElement(element);
+      var packageMeta = new PackageMeta.fromElement(element, config);
       var lib = new Library._(
           element, this, new Package.fromPackageMeta(packageMeta, this));
       packageMap[packageMeta.name]._libraries.add(lib);
@@ -4552,7 +4552,7 @@ class PackageGraph extends Canonicalization
           e.library,
           this,
           new Package.fromPackageMeta(
-              new PackageMeta.fromElement(e.library), packageGraph));
+              new PackageMeta.fromElement(e.library, config), packageGraph));
       allLibraries[e.library] = foundLibrary;
     }
     return foundLibrary;
@@ -5407,7 +5407,7 @@ class PackageBuilder {
       if (library != null) {
         if (!config.isLibraryExcluded(Library.getLibraryName(library)) &&
             !config.excludePackages
-                .contains(new PackageMeta.fromElement(library)?.name)) {
+                .contains(new PackageMeta.fromElement(library, config)?.name)) {
           libraries.add(library);
           sources.add(source);
         }