add a --no-generate-docs flag that is faster and only displays warnings (#1909)

* basic non-documenting mode works

* Basically works now, needs tests

* Add a test

* dartfmt

* Cleanup

* Add test for doc generation presence/absence with --quiet

* Fix packages output parsing problem

Author: jcollins-g

bin/dartdoc.dart

@@ -20,6 +20,7 @@ class DartdocProgramOptionContext extends DartdocGeneratorOptionContext
       : super(optionSet, dir);
 
   bool get asyncStackTraces => optionSet['asyncStackTraces'].valueAt(context);
+  bool get generateDocs => optionSet['generateDocs'].valueAt(context);
   bool get help => optionSet['help'].valueAt(context);
   bool get version => optionSet['version'].valueAt(context);
 }
@@ -29,6 +30,10 @@ Future<List<DartdocOption>> createDartdocProgramOptions() async {
     new DartdocOptionArgOnly<bool>('asyncStackTraces', false,
         help: 'Display coordinated asynchronous stack traces (slow)',
         negatable: true),
+    new DartdocOptionArgOnly<bool>('generateDocs', true,
+        help:
+            'Generate docs into the output directory (or only display warnings if false).',
+        negatable: true),
     new DartdocOptionArgOnly<bool>('help', false,
         abbr: 'h', help: 'Show command help.', negatable: false),
     new DartdocOptionArgOnly<bool>('version', false,
@@ -82,29 +87,23 @@ Future<void> main(List<String> arguments) async {
   }
   startLogging(config);
 
-  Directory outputDir = new Directory(config.output);
-  logInfo("Generating documentation for '${config.topLevelPackageMeta}' into "
-      "${outputDir.absolute.path}${Platform.pathSeparator}");
-
-  Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(config);
-
+  Dartdoc dartdoc = config.generateDocs
+      ? await Dartdoc.withDefaultGenerators(config)
+      : await Dartdoc.withEmptyGenerator(config);
   dartdoc.onCheckProgress.listen(logProgress);
   try {
     await Chain.capture(() async {
-      await runZoned(() async {
-        DartdocResults results = await dartdoc.generateDocs();
-        logInfo('Success! Docs generated into ${results.outDir.absolute.path}');
-      },
+      await runZoned(dartdoc.generateDocs,
           zoneSpecification: new ZoneSpecification(
               print: (Zone self, ZoneDelegate parent, Zone zone, String line) =>
                   logPrint(line)));
     }, onError: (e, Chain chain) {
       if (e is DartdocFailure) {
-        stderr.writeln('\nGeneration failed: ${e}.');
+        stderr.writeln('\ndartdoc failed: ${e}.');
         exitCode = 1;
         return;
       } else {
-        stderr.writeln('\nGeneration failed: ${e}\n${chain.terse}');
+        stderr.writeln('\ndartdoc failed: ${e}\n${chain.terse}');
         exitCode = 255;
         return;
       }

lib/dartdoc.dart

@@ -68,6 +68,12 @@ class Dartdoc extends PackageBuilder {
     return new Dartdoc._(config, generators);
   }
 
+  /// An asynchronous factory method that builds
+  static Future<Dartdoc> withEmptyGenerator(DartdocOptionContext config) async {
+    List<Generator> generators = await initEmptyGenerators(config);
+    return new Dartdoc._(config, generators);
+  }
+
   /// Basic synchronous factory that gives a stripped down Dartdoc that won't
   /// use generators.  Useful for testing.
   factory Dartdoc.withoutGenerators(DartdocOptionContext config) {
@@ -101,7 +107,8 @@ class Dartdoc extends PackageBuilder {
         await generator.generate(packageGraph, outputDir.path);
         writtenFiles.addAll(generator.writtenFiles.map(pathLib.normalize));
       }
-      if (config.validateLinks) validateLinks(packageGraph, outputDir.path);
+      if (config.validateLinks && writtenFiles.isNotEmpty)
+        validateLinks(packageGraph, outputDir.path);
     }
 
     int warnings = packageGraph.packageWarningCounter.warningCount;
@@ -122,6 +129,8 @@ class Dartdoc extends PackageBuilder {
   }
 
   Future<DartdocResults> generateDocs() async {
+    logPrint("Documenting ${config.topLevelPackageMeta}...");
+
     DartdocResults dartdocResults = await generateDocsBase();
     if (dartdocResults.packageGraph.localPublicLibraries.isEmpty) {
       throw new DartdocFailure(
@@ -134,7 +143,8 @@ class Dartdoc extends PackageBuilder {
       throw new DartdocFailure(
           "dartdoc encountered $errorCount} errors while processing.");
     }
-
+    logInfo(
+        'Success! Docs generated into ${dartdocResults.outDir.absolute.path}');
     return dartdocResults;
   }
 

lib/src/empty_generator.dart

@@ -0,0 +1,41 @@
+library dartdoc.empty_generator;
+
+import 'dart:async';
+
+import 'package:dartdoc/src/generator.dart';
+import 'package:dartdoc/src/model.dart';
+import 'package:dartdoc/src/model_utils.dart';
+
+/// A generator that does not generate files, but does traverse the [PackageGraph]
+/// and access [ModelElement.documetationAsHtml] for every element as though
+/// it were.
+class EmptyGenerator extends Generator {
+  @override
+  Future generate(PackageGraph _packageGraph, String outputDirectoryPath) {
+    _onFileCreated.add(_packageGraph.defaultPackage.documentationAsHtml);
+    for (var package in Set.from([_packageGraph.defaultPackage])
+      ..addAll(_packageGraph.localPackages)) {
+      for (var category in filterNonDocumented(package.categories)) {
+        _onFileCreated.add(category.documentationAsHtml);
+      }
+
+      for (Library lib in filterNonDocumented(package.libraries)) {
+        filterNonDocumented(lib.allModelElements)
+            .forEach((m) => _onFileCreated.add(m.documentationAsHtml));
+      }
+    }
+    return null;
+  }
+
+  final StreamController<void> _onFileCreated =
+      new StreamController(sync: true);
+
+  @override
+
+  /// Implementation fires on each model element processed rather than
+  /// file creation.
+  Stream<void> get onFileCreated => _onFileCreated.stream;
+
+  @override
+  Set<String> get writtenFiles => new Set();
+}

lib/src/generator.dart

@@ -6,7 +6,6 @@
 library dartdoc.generator;
 
 import 'dart:async' show Stream, Future;
-import 'dart:io' show File;
 
 import 'package:dartdoc/src/model.dart' show PackageGraph;
 
@@ -20,7 +19,7 @@ abstract class Generator {
   Future generate(PackageGraph packageGraph, String outputDirectoryPath);
 
   /// Fires when a file is created.
-  Stream<File> get onFileCreated;
+  Stream<void> get onFileCreated;
 
   /// Fetches all filenames written by this generator.
   Set<String> get writtenFiles;

lib/src/html/html_generator.dart

@@ -9,6 +9,7 @@ import 'dart:io' show Directory, File;
 import 'dart:isolate';
 
 import 'package:dartdoc/dartdoc.dart';
+import 'package:dartdoc/src/empty_generator.dart';
 import 'package:dartdoc/src/generator.dart';
 import 'package:dartdoc/src/html/html_generator_instance.dart';
 import 'package:dartdoc/src/html/template_data.dart';
@@ -41,11 +42,11 @@ class HtmlGenerator extends Generator {
   final HtmlGeneratorOptions _options;
   HtmlGeneratorInstance _instance;
 
-  final StreamController<File> _onFileCreated =
+  final StreamController<void> _onFileCreated =
       new StreamController(sync: true);
 
   @override
-  Stream<File> get onFileCreated => _onFileCreated.stream;
+  Stream<void> get onFileCreated => _onFileCreated.stream;
 
   @override
   final Set<String> writtenFiles = new Set<String>();
@@ -131,6 +132,10 @@ class HtmlGeneratorOptions implements HtmlOptions {
       : this.toolVersion = toolVersion ?? 'unknown';
 }
 
+Future<List<Generator>> initEmptyGenerators(DartdocOptionContext config) async {
+  return [EmptyGenerator()];
+}
+
 /// Initialize and setup the generators.
 Future<List<Generator>> initGenerators(GeneratorContext config) async {
   // TODO(jcollins-g): Rationalize based on GeneratorContext all the way down

lib/src/logging.dart

@@ -96,13 +96,15 @@ void startLogging(LoggingContext config) {
       assert(message.isNotEmpty);
 
       if (record.level < Level.WARNING) {
-        if (config.showProgress && message.endsWith('...')) {
-          // Assume there may be more progress to print, so omit the trailing
-          // newline
-          writingProgress = true;
-          stdout.write(message);
-        } else {
-          print(message);
+        if (!config.quiet) {
+          if (config.showProgress && message.endsWith('...')) {
+            // Assume there may be more progress to print, so omit the trailing
+            // newline
+            writingProgress = true;
+            stdout.write(message);
+          } else {
+            print(message);
+          }
         }
       } else {
         stderr.writeln(message);
@@ -114,6 +116,7 @@ void startLogging(LoggingContext config) {
 abstract class LoggingContext implements DartdocOptionContextBase {
   bool get json => optionSet['json'].valueAt(context);
   bool get showProgress => optionSet['showProgress'].valueAt(context);
+  bool get quiet => optionSet['quiet'].valueAt(context);
 }
 
 Future<List<DartdocOption>> createLoggingOptions() async {
@@ -124,5 +127,15 @@ Future<List<DartdocOption>> createLoggingOptions() async {
     new DartdocOptionArgOnly<bool>('showProgress', false,
         help: 'Display progress indications to console stdout',
         negatable: false),
+    new DartdocOptionArgSynth<bool>('quiet',
+        (DartdocSyntheticOption option, Directory dir) {
+      if (option.root['generateDocs']?.valueAt(dir) == false) {
+        return true;
+      }
+      return false;
+    },
+        abbr: 'q',
+        negatable: true,
+        help: 'Only show warnings and errors; silence all other output.'),
   ];
 }

lib/src/model.dart

@@ -3251,7 +3251,8 @@ abstract class ModelElement extends Canonicalization
 
   /// Separate from _buildDocumentationLocal for overriding.
   String _buildDocumentationBaseSync() {
-    assert(_rawDocs == null, 'reentrant calls to _buildDocumentation* not allowed');
+    assert(_rawDocs == null,
+        'reentrant calls to _buildDocumentation* not allowed');
     // Do not use the sync method if we need to evaluate tools or templates.
     assert(!isCanonical ||
         !needsPrecacheRegExp.hasMatch(documentationComment ?? ''));
@@ -3271,7 +3272,8 @@ abstract class ModelElement extends Canonicalization
   /// Separate from _buildDocumentationLocal for overriding.  Can only be
   /// used as part of [PackageGraph.setUpPackageGraph].
   Future<String> _buildDocumentationBase() async {
-    assert(_rawDocs == null, 'reentrant calls to _buildDocumentation* not allowed');
+    assert(_rawDocs == null,
+        'reentrant calls to _buildDocumentation* not allowed');
     // Do not use the sync method if we need to evaluate tools or templates.
     if (config.dropTextFrom.contains(element.library.name)) {
       _rawDocs = '';

test/dartdoc_test.dart

@@ -131,6 +131,36 @@ void main() {
         await Future.wait(CoverageSubprocessLauncher.coverageResults);
       });
 
+      test('running --no-generate-docs is quiet and does not generate docs',
+          () async {
+        Directory outputDir =
+            await Directory.systemTemp.createTemp('dartdoc.testEmpty.');
+        List<String> outputLines = [];
+        await subprocessLauncher.runStreamed(Platform.resolvedExecutable,
+            [dartdocPath, '--output', outputDir.path, '--no-generate-docs'],
+            perLine: outputLines.add, workingDirectory: _testPackagePath);
+        expect(outputLines, isNot(contains(matches('^parsing'))));
+        expect(outputLines, contains(matches('^  warning:')));
+        expect(
+            outputLines.last, matches(r'^found \d+ warnings and \d+ errors'));
+        expect(outputDir.listSync(), isEmpty);
+      });
+
+      test('running --quiet is quiet and does generate docs',
+          () async {
+        Directory outputDir =
+        await Directory.systemTemp.createTemp('dartdoc.testEmpty.');
+        List<String> outputLines = [];
+        await subprocessLauncher.runStreamed(Platform.resolvedExecutable,
+          [dartdocPath, '--output', outputDir.path, '--quiet'],
+          perLine: outputLines.add, workingDirectory: _testPackagePath);
+        expect(outputLines, isNot(contains(matches('^parsing'))));
+        expect(outputLines, contains(matches('^  warning:')));
+        expect(
+          outputLines.last, matches(r'^found \d+ warnings and \d+ errors'));
+        expect(outputDir.listSync(), isNotEmpty);
+      });
+
       test('invalid parameters return non-zero and print a fatal-error',
           () async {
         List outputLines = [];

test/model_test.dart

@@ -676,7 +676,8 @@ void main() {
     });
 
     test('can be reexported even if the file suffix is not .dart', () {
-      expect(fakeLibrary.allClasses.map((c) => c.name), contains('MyClassFromADartFile'));
+      expect(fakeLibrary.allClasses.map((c) => c.name),
+          contains('MyClassFromADartFile'));
     });
 
     test('that is deprecated has a deprecated css class in linkedName', () {

test/src/utils.dart

@@ -160,12 +160,14 @@ class CoverageSubprocessLauncher extends SubprocessLauncher {
       'coverage:format_coverage',
       '--lcov',
       '-v',
-      '-b', '.',
+      '-b',
+      '.',
       '--packages=.packages',
       '--sdk-root=${pathLib.canonicalize(pathLib.join(pathLib.dirname(Platform.executable), '..'))}',
       '--out=${pathLib.canonicalize(outputFile.path)}',
       '--report-on=bin,lib',
-      '-i', tempDir.path,
+      '-i',
+      tempDir.path,
     ]);
   }
 

tool/travis.sh

@@ -34,7 +34,7 @@ elif [ "$DARTDOC_BOT" = "packages" ]; then
   fi
   PACKAGE_NAME=access PACKAGE_VERSION=">=1.0.1+2" pub run grinder build-pub-package
   # Negative test for flutter_plugin_tools, make sure right error message is displayed.
-  PACKAGE_NAME=flutter_plugin_tools PACKAGE_VERSION=">=0.0.14+1" pub run grinder build-pub-package 2>&1 | grep "Generation failed: dartdoc could not find any libraries to document.$"
+  PACKAGE_NAME=flutter_plugin_tools PACKAGE_VERSION=">=0.0.14+1" pub run grinder build-pub-package 2>&1 | grep "dartdoc failed: dartdoc could not find any libraries to document.$"
   PACKAGE_NAME=shelf_exception_handler PACKAGE_VERSION=">=0.2.0" pub run grinder build-pub-package
 elif [ "$DARTDOC_BOT" = "sdk-analyzer" ]; then
   echo "Running main dartdoc bot against the SDK analyzer"