Add include/exclude to supported config options (#1700)

* Add include/exclude to supported config options

* Cleanup and more consistently use buildDartdoc in test

* dartfmt and sort options in readme

Author: jcollins-g

README.md

@@ -111,6 +111,9 @@ Unrecognized options will be ignored.  Supported options:
 
   * **categoryOrder**:  Specify the order of categories, below, for display in the sidebar and
     the package page.
+  * **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.
   * **linkTo**:  For other packages depending on this one, if this map is defined those packages
     will use the settings here to control how hyperlinks to the package are generated.
     This will override the default for packages hosted on pub.dartlang.org.
@@ -133,12 +136,10 @@ as POSIX paths.  Dartdoc will convert POSIX paths automatically on Windows.
   * **ambiguousReexportScorerMinConfidence**:  The ambiguous reexport scorer will emit a warning if
   it is not at least this confident.  Default: 0.1
   * **examplePathPrefix**:  Specify the prefix for the example paths, defaulting to the project root.
-  * **exclude**:  Specify a list of library names to avoid generating docs for, ignoring all others.
   * **favicon**:  A path to a favicon for the generated docs.
   * **footer**: A list of paths to footer files containing HTML text.
   * **footerText**: A list of paths to text files for optional text next to the package name and version
   * **header**:  A list of paths to header files containing HTML text.
-  * **include**:  Specify a list of library names to generate docs for, ignoring all others.
   * **includeExternal**:  Specify a list of library filenames to add to the list of documented libraries.
 
 ### Categories

bin/dartdoc.dart

@@ -42,9 +42,6 @@ main(List<String> arguments) async {
     createGeneratorOptions,
   ]);
 
-  DartdocProgramOptionContext config =
-      new DartdocProgramOptionContext(optionSet, Directory.current);
-
   try {
     optionSet.parseArguments(arguments);
   } on FormatException catch (e) {
@@ -63,6 +60,8 @@ main(List<String> arguments) async {
     _printVersionAndExit(optionSet.argParser);
   }
 
+  DartdocProgramOptionContext config =
+      new DartdocProgramOptionContext(optionSet, null);
   startLogging(config);
 
   Directory outputDir = new Directory(config.output);

lib/src/dartdoc_options.dart

@@ -883,9 +883,17 @@ class DartdocOptionContext {
   // TODO(jcollins-g): Allow passing in structured data to initialize a
   // [DartdocOptionContext]'s arguments instead of having to parse strings
   // via optionSet.
+  /// If [entity] is null, assume this is the initialization case and use
+  /// the inputDir flag to determine the context.
   DartdocOptionContext(this.optionSet, FileSystemEntity entity) {
-    context = new Directory(pathLib
-        .canonicalize(entity is File ? entity.parent.path : entity.path));
+    if (entity == null) {
+      String inputDir = optionSet['inputDir'].valueAt(Directory.current) ??
+          Directory.current.path;
+      context = new Directory(inputDir);
+    } else {
+      context = new Directory(pathLib
+          .canonicalize(entity is File ? entity.parent.path : entity.path));
+    }
   }
 
   /// Build a DartdocOptionContext from an analyzer element (using its source

lib/src/model.dart

@@ -3597,7 +3597,8 @@ abstract class ModelElement extends Canonicalization
         width = int.parse(match[2]);
       } on FormatException {
         warn(PackageWarning.invalidParameter,
-            message: 'An animation has an invalid width ($name): ${match[2]}. The '
+            message:
+                'An animation has an invalid width ($name): ${match[2]}. The '
                 'width must be an integer.');
         return '';
       }
@@ -3606,7 +3607,8 @@ abstract class ModelElement extends Canonicalization
         height = int.parse(match[3]);
       } on FormatException {
         warn(PackageWarning.invalidParameter,
-            message: 'An animation has an invalid height ($name): ${match[3]}. The '
+            message:
+                'An animation has an invalid height ($name): ${match[3]}. The '
                 'height must be an integer.');
         return '';
       }
@@ -3615,7 +3617,8 @@ abstract class ModelElement extends Canonicalization
         movieUrl = Uri.parse(match[4]);
       } on FormatException catch (e) {
         warn(PackageWarning.invalidParameter,
-            message: 'An animation URL could not be parsed ($name): ${match[4]}\n$e');
+            message:
+                'An animation URL could not be parsed ($name): ${match[4]}\n$e');
         return '';
       }
       final String overlayName = '${name}_play_button_';
@@ -3655,7 +3658,7 @@ abstract class ModelElement extends Canonicalization
   </video>
 </div>
 
-''';  // String must end at beginning of line, or following inline text will be
+'''; // String must end at beginning of line, or following inline text will be
       // indented.
     });
   }
@@ -5742,7 +5745,8 @@ class PackageBuilder {
     if (config.include.isNotEmpty) {
       Iterable knownLibraryNames = libraries.map((l) => l.name);
       Set notFound = new Set.from(config.include)
-          .difference(new Set.from(knownLibraryNames));
+          .difference(new Set.from(knownLibraryNames))
+          .difference(new Set.from(config.exclude));
       if (notFound.isNotEmpty) {
         throw 'Did not find: [${notFound.join(', ')}] in '
             'known libraries: [${knownLibraryNames.join(', ')}]';

test/dartdoc_test.dart

@@ -9,7 +9,6 @@ import 'dart:io';
 
 import 'package:dartdoc/dartdoc.dart';
 import 'package:dartdoc/src/model.dart';
-import 'package:dartdoc/src/package_meta.dart';
 import 'package:path/path.dart' as pathLib;
 import 'package:test/test.dart';
 
@@ -28,24 +27,51 @@ void main() {
       delete(tempDir);
     });
 
-    Future<DartdocGeneratorOptionContext> generatorContextFromArgvTemp(
-        List<String> argv) async {
-      return await generatorContextFromArgv(argv..addAll(outputParam));
+    Future<Dartdoc> buildDartdoc(
+        List<String> argv, Directory packageRoot) async {
+      return await Dartdoc.withDefaultGenerators(await generatorContextFromArgv(
+          argv..addAll(['--input', packageRoot.path])..addAll(outputParam)));
     }
 
+    group('include/exclude parameters', () {
+      test('with config file', () async {
+        Dartdoc dartdoc = await buildDartdoc([], testPackageImportExport);
+        DartdocResults results = await dartdoc.generateDocs();
+        PackageGraph p = results.packageGraph;
+        expect(p.localPublicLibraries.map((l) => l.name),
+            orderedEquals(['explicitly_included', 'more_included']));
+      });
+
+      test('with include command line argument', () async {
+        Dartdoc dartdoc = await buildDartdoc(
+            ['--include', 'another_included'], testPackageImportExport);
+        DartdocResults results = await dartdoc.generateDocs();
+        PackageGraph p = results.packageGraph;
+        expect(p.localPublicLibraries.length, equals(1));
+        expect(p.localPublicLibraries.first.name, equals('another_included'));
+      });
+
+      test('with exclude command line argument', () async {
+        Dartdoc dartdoc = await buildDartdoc(
+            ['--exclude', 'more_included'], testPackageImportExport);
+        DartdocResults results = await dartdoc.generateDocs();
+        PackageGraph p = results.packageGraph;
+        expect(p.localPublicLibraries.length, equals(1));
+        expect(
+            p.localPublicLibraries.first.name, equals('explicitly_included'));
+      });
+    });
+
     test('package without version produces valid semver in docs', () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageMinimumDir.path]));
+      Dartdoc dartdoc = await buildDartdoc([], testPackageMinimumDir);
       DartdocResults results = await dartdoc.generateDocs();
       PackageGraph p = results.packageGraph;
-      assert(p.defaultPackage.version == '0.0.0-unknown');
+      expect(p.defaultPackage.version, equals('0.0.0-unknown'));
     });
 
     test('basic interlinking test', () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageDir.path, '--link-to-remote']));
+      Dartdoc dartdoc =
+          await buildDartdoc(['--link-to-remote'], testPackageDir);
       DartdocResults results = await dartdoc.generateDocs();
       PackageGraph p = results.packageGraph;
       Package tuple = p.publicPackages.firstWhere((p) => p.name == 'tuple');
@@ -73,8 +99,7 @@ void main() {
 
     test('generate docs for ${pathLib.basename(testPackageDir.path)} works',
         () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(['--input', testPackageDir.path]));
+      Dartdoc dartdoc = await buildDartdoc([], testPackageDir);
 
       DartdocResults results = await dartdoc.generateDocs();
       expect(results.packageGraph, isNotNull);
@@ -89,9 +114,7 @@ void main() {
 
     test('generate docs for ${pathLib.basename(testPackageBadDir.path)} fails',
         () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageBadDir.path]));
+      Dartdoc dartdoc = await buildDartdoc([], testPackageBadDir);
 
       try {
         await dartdoc.generateDocs();
@@ -102,9 +125,7 @@ void main() {
     });
 
     test('generate docs for a package that does not have a readme', () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageWithNoReadme.path]));
+      Dartdoc dartdoc = await buildDartdoc([], testPackageWithNoReadme);
 
       DartdocResults results = await dartdoc.generateDocs();
       expect(results.packageGraph, isNotNull);
@@ -117,9 +138,8 @@ void main() {
     });
 
     test('generate docs including a single library', () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageDir.path, '--include', 'fake']));
+      Dartdoc dartdoc =
+          await buildDartdoc(['--include', 'fake'], testPackageDir);
 
       DartdocResults results = await dartdoc.generateDocs();
       expect(results.packageGraph, isNotNull);
@@ -132,9 +152,8 @@ void main() {
     });
 
     test('generate docs excluding a single library', () async {
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageDir.path, '--exclude', 'fake']));
+      Dartdoc dartdoc =
+          await buildDartdoc(['--exclude', 'fake'], testPackageDir);
 
       DartdocResults results = await dartdoc.generateDocs();
       expect(results.packageGraph, isNotNull);
@@ -148,11 +167,7 @@ void main() {
     });
 
     test('generate docs for package with embedder yaml', () async {
-      PackageMeta meta = new PackageMeta.fromDir(testPackageWithEmbedderYaml);
-      if (meta.needsPubGet) meta.runPubGet();
-      Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(
-          await generatorContextFromArgvTemp(
-              ['--input', testPackageWithEmbedderYaml.path]));
+      Dartdoc dartdoc = await buildDartdoc([], testPackageWithEmbedderYaml);
 
       DartdocResults results = await dartdoc.generateDocs();
       expect(results.packageGraph, isNotNull);

test/model_test.dart

@@ -576,14 +576,11 @@ void main() {
           isTrue);
     });
     test("Doesn't place animations in one line doc", () {
-      expect(
-          withAnimationInline.oneLineDoc, isNot(contains('<video')));
-      expect(
-          withAnimationInline.documentation, contains('<video'));
+      expect(withAnimationInline.oneLineDoc, isNot(contains('<video')));
+      expect(withAnimationInline.documentation, contains('<video'));
     });
     test("Handles animations inline properly", () {
-      expect(
-          withAnimationInline.documentation, isNot(contains('  works')));
+      expect(withAnimationInline.documentation, isNot(contains('  works')));
     });
   });
 

test/src/utils.dart

@@ -27,15 +27,18 @@ final Directory testPackageWithEmbedderYaml =
     new Directory('testing/test_package_embedder_yaml');
 final Directory testPackageWithNoReadme =
     new Directory('testing/test_package_small');
+final Directory testPackageImportExport =
+    new Directory('testing/test_package_include_exclude');
 
 /// Convenience factory to build a [DartdocGeneratorOptionContext] and associate
-/// it with a [DartdocOptionSet] based on the current working directory.
+/// it with a [DartdocOptionSet] based on the current working directory and/or
+/// the '--input' flag.
 Future<DartdocGeneratorOptionContext> generatorContextFromArgv(
     List<String> argv) async {
   DartdocOptionSet optionSet = await DartdocOptionSet.fromOptionGenerators(
       'dartdoc', [createDartdocOptions, createGeneratorOptions]);
   optionSet.parseArguments(argv);
-  return new DartdocGeneratorOptionContext(optionSet, Directory.current);
+  return new DartdocGeneratorOptionContext(optionSet, null);
 }
 
 /// Convenience factory to build a [DartdocOptionContext] and associate it with a

testing/.gitignore

@@ -0,0 +1,4 @@
+*/doc/api/
+*/ios
+*/pubspec.lock
+*/.packages

testing/test_package/.gitignore

@@ -0,0 +1,6 @@
+/// This is a libraryish thing in the wrong place.
+library included;
+
+void main() {
+  print('hello, world');
+}

testing/test_package_bad/.gitignore

@@ -0,0 +1,5 @@
+library not_included;
+
+void main() {
+  print('another binary not included');
+}

testing/test_package_flutter_plugin/.gitignore

@@ -0,0 +1,3 @@
+dartdoc:
+  include: ['explicitly_included', 'more_included']
+  exclude: ['excluded']

testing/test_package_imported/.gitignore

@@ -0,0 +1 @@
+library another_included;

testing/test_package_include_exclude/bin/included.dart

@@ -0,0 +1 @@
+library excluded;

testing/test_package_include_exclude/bin/not_included.dart

@@ -0,0 +1 @@
+library explicitly_included;

testing/test_package_include_exclude/dartdoc_options.yaml

@@ -0,0 +1 @@
+library more_included;

testing/test_package_include_exclude/lib/another_included.dart

@@ -0,0 +1 @@
+library not_explicitly_included;

testing/test_package_include_exclude/lib/excluded.dart

@@ -0,0 +1 @@
+library included_under_src;

testing/test_package_include_exclude/lib/explicitly_included.dart

@@ -0,0 +1,2 @@
+name: test_package_include_exclude
+version: 0.0.1