Generator backend for Markdown (#2151)

* Create Markdown generator backend

* Load markdown templates

Note we need to maintain enumerated lists of partials in order to build
resource URIs.

Author: jdkoren

lib/dartdoc.dart

@@ -16,6 +16,7 @@ import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/generator/empty_generator.dart';
 import 'package:dartdoc/src/generator/generator.dart';
 import 'package:dartdoc/src/generator/html_generator.dart';
+import 'package:dartdoc/src/generator/markdown_generator.dart';
 import 'package:dartdoc/src/logging.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_meta.dart';
@@ -109,7 +110,7 @@ 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')
+  @Deprecated('Prefer fromContext() instead')
   static Future<Dartdoc> withDefaultGenerators(
       DartdocGeneratorOptionContext config) async {
     return Dartdoc._(config, await initHtmlGenerator(config));
@@ -130,8 +131,7 @@ class Dartdoc extends PackageBuilder {
         generator = await initHtmlGenerator(context);
         break;
       case 'md':
-        // TODO(jdkoren): use a real generator
-        generator = await initEmptyGenerator(context);
+        generator = await initMarkdownGenerator(context);
         break;
       default:
         throw DartdocFailure('Unsupported output format: ${context.format}');

lib/src/generator/markdown_generator.dart

@@ -0,0 +1,35 @@
+// Copyright (c) 2020, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:dartdoc/dartdoc.dart';
+import 'package:dartdoc/src/generator/dartdoc_generator_backend.dart';
+import 'package:dartdoc/src/generator/generator.dart';
+import 'package:dartdoc/src/generator/generator_frontend.dart';
+import 'package:dartdoc/src/generator/template_data.dart';
+import 'package:dartdoc/src/generator/templates.dart';
+import 'package:dartdoc/src/model/package.dart';
+import 'package:dartdoc/src/model/package_graph.dart';
+
+Future<Generator> initMarkdownGenerator(
+    DartdocGeneratorOptionContext context) async {
+  var templates = await Templates.fromContext(context);
+  var options = DartdocGeneratorBackendOptions.fromContext(context);
+  var backend = MarkdownGeneratorBackend(options, templates);
+  return GeneratorFrontEnd(backend);
+}
+
+/// Generator backend for markdown output.
+class MarkdownGeneratorBackend extends DartdocGeneratorBackend {
+  MarkdownGeneratorBackend(
+      DartdocGeneratorBackendOptions options, Templates templates)
+      : super(options, templates);
+
+  @override
+  void generatePackage(FileWriter writer, PackageGraph graph, Package package) {
+    super.generatePackage(writer, graph, package);
+    // We have to construct the data again. This only happens once per package.
+    TemplateData data = PackageTemplateData(options, graph, package);
+    render(writer, '__404error.md', templates.errorTemplate, data);
+  }
+}

lib/src/generator/templates.dart

@@ -13,7 +13,9 @@ import 'package:dartdoc/src/generator/resource_loader.dart' as loader;
 import 'package:mustache/mustache.dart';
 import 'package:path/path.dart' as path;
 
-const _partials = <String>[
+// resource_loader and the Resource API doesn't support viewing resources like
+// a directory listing, so we have to explicitly list the partials.
+const _partials_html = <String>[
   'callable',
   'callable_multiline',
   'categorization',
@@ -42,6 +44,27 @@ const _partials = <String>[
   'accessor_setter',
 ];
 
+const _partials_md = <String>[
+  'accessor_getter',
+  'accessor_setter',
+  'callable',
+  'callable_multiline',
+  'categorization',
+  'class',
+  'constant',
+  'documentation',
+  'extension',
+  'features',
+  'footer',
+  'head',
+  'library',
+  'mixin',
+  'name_summary',
+  'property',
+  'source_code',
+  'source_link',
+];
+
 const String _headerPlaceholder = '{{! header placeholder }}';
 const String _footerPlaceholder = '{{! footer placeholder }}';
 const String _footerTextPlaceholder = '{{! footer-text placeholder }}';
@@ -82,17 +105,33 @@ abstract class _TemplatesLoader {
 /// Loads default templates included in the Dartdoc program.
 class _DefaultTemplatesLoader extends _TemplatesLoader {
   final String _format;
+  final List<String> _partials;
+
+  factory _DefaultTemplatesLoader.create(String format) {
+    List<String> partials;
+    switch (format) {
+      case 'html':
+        partials = _partials_html;
+        break;
+      case 'md':
+        partials = _partials_md;
+        break;
+      default:
+        partials = [];
+    }
+    return _DefaultTemplatesLoader(format, partials);
+  }
 
-  _DefaultTemplatesLoader(this._format);
+  _DefaultTemplatesLoader(this._format, this._partials);
 
   @override
   Future<Map<String, String>> loadPartials() async {
-    var partials = <String, String>{};
+    var templates = <String, String>{};
     for (String name in _partials) {
       var uri = 'package:dartdoc/templates/$_format/_$name.$_format';
-      partials[name] = await loader.loadAsString(uri);
+      templates[name] = await loader.loadAsString(uri);
     }
-    return partials;
+    return templates;
   }
 
   @override
@@ -178,7 +217,7 @@ class Templates {
       {List<String> headerPaths,
       List<String> footerPaths,
       List<String> footerTextPaths}) async {
-    return _create(_DefaultTemplatesLoader(format),
+    return _create(_DefaultTemplatesLoader.create(format),
         headerPaths: headerPaths,
         footerPaths: footerPaths,
         footerTextPaths: footerTextPaths);