Add config option for output format (#2132)

* Add config option for output format

Defaults to 'html', but also supports 'md' (using empty generator).
Option is hidden for now until a real generator for 'md' is wired up.

* Code review changes

* Add message to deprecated annotation

Author: jdkoren

bin/dartdoc.dart

@@ -87,7 +87,7 @@ Future<void> main(List<String> arguments) async {
   startLogging(config);
 
   Dartdoc dartdoc = config.generateDocs
-      ? await Dartdoc.withDefaultGenerators(config)
+      ? await Dartdoc.fromContext(config)
       : await Dartdoc.withEmptyGenerator(config);
   dartdoc.onCheckProgress.listen(logProgress);
   try {

lib/dartdoc.dart

@@ -109,16 +109,36 @@ class Dartdoc extends PackageBuilder {
 
   /// An asynchronous factory method that builds Dartdoc's file writers
   /// and returns a Dartdoc object with them.
+  @Deprecated('Prefer withContext() instead')
   static Future<Dartdoc> withDefaultGenerators(
       DartdocGeneratorOptionContext config) async {
     return Dartdoc._(config, await initHtmlGenerator(config));
   }
 
-  /// An asynchronous factory method that builds
+  /// Asynchronous factory method that builds Dartdoc with an empty generator.
   static Future<Dartdoc> withEmptyGenerator(DartdocOptionContext config) async {
     return Dartdoc._(config, await initEmptyGenerator(config));
   }
 
+  /// Asynchronous factory method that builds Dartdoc with a generator
+  /// determined by the given context.
+  static Future<Dartdoc> fromContext(
+      DartdocGeneratorOptionContext context) async {
+    Generator generator;
+    switch (context.format) {
+      case 'html':
+        generator = await initHtmlGenerator(context);
+        break;
+      case 'md':
+        // TODO(jdkoren): use a real generator
+        generator = await initEmptyGenerator(context);
+        break;
+      default:
+        throw DartdocFailure('Unsupported output format: ${context.format}');
+    }
+    return Dartdoc._(context, generator);
+  }
+
   Stream<String> get onCheckProgress => _onCheckProgress.stream;
 
   PackageGraph packageGraph;

lib/src/generator.dart

@@ -56,6 +56,9 @@ mixin GeneratorContext on DartdocOptionContextBase {
 
   String get templatesDir => optionSet['templatesDir'].valueAt(context);
 
+  /// Output format, e.g. 'html', 'md'
+  String get format => optionSet['format'].valueAt(context);
+
   // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.
   bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
 }
@@ -137,6 +140,8 @@ Future<List<DartdocOption>> createGeneratorOptions() async {
             'top_level_property, typedef. Partial templates are supported; '
             'they must begin with an underscore, and references to them must '
             'omit the leading underscore (e.g. use {{>foo}} to reference the '
-            'partial template _foo.html).'),
+            'partial template named _foo).'),
+    // TODO(jdkoren): Unhide when we have good support for another format.
+    DartdocOptionArgOnly<String>('format', 'html', hide: true),
   ];
 }

test/dartdoc_test.dart

@@ -45,9 +45,8 @@ void main() {
 
     Future<Dartdoc> buildDartdoc(
         List<String> argv, Directory packageRoot, Directory tempDir) async {
-      return await Dartdoc.withDefaultGenerators(await generatorContextFromArgv(
-          argv
-            ..addAll(['--input', packageRoot.path, '--output', tempDir.path])));
+      return await Dartdoc.fromContext(await generatorContextFromArgv(argv
+        ..addAll(['--input', packageRoot.path, '--output', tempDir.path])));
     }
 
     group('Option handling', () {
@@ -425,5 +424,16 @@ void main() {
       expect(level2.readAsStringSync(),
           contains('<link rel="canonical" href="$prefix/ex/Apple/m.html">'));
     });
+
+    test('generate docs with bad output format', () async {
+      try {
+        await buildDartdoc(['--format', 'bad'], testPackageDir, tempDir);
+        fail('dartdoc should fail with bad output format');
+      } catch (e) {
+        expect(e is DartdocFailure, isTrue);
+        expect((e as DartdocFailure).message,
+            startsWith('Unsupported output format'));
+      }
+    });
   }, timeout: Timeout.factor(8));
 }