Use Mustachio AOT compiler for default templates

Author: srawlins

lib/dartdoc.dart

@@ -114,7 +114,7 @@ class DartdocFileWriter implements FileWriter {
 /// Generates Dart documentation for all public Dart libraries in the given
 /// directory.
 class Dartdoc {
-  final Generator generator;
+  Generator _generator;
   final PackageBuilder packageBuilder;
   final DartdocOptionContext config;
   final Set<String> _writtenFiles = {};
@@ -124,12 +124,23 @@ class Dartdoc {
   final StreamController<String> _onCheckProgress =
       StreamController(sync: true);
 
-  Dartdoc._(this.config, this.generator, this.packageBuilder) {
+  Dartdoc._(this.config, this._generator, this.packageBuilder) {
     _outputDir = config.resourceProvider
         .getFolder(config.resourceProvider.pathContext.absolute(config.output))
           ..create();
   }
 
+  // TODO(srawlins): Remove when https://github.com/dart-lang/linter/issues/2706
+  // is fixed.
+  // ignore: unnecessary_getters_setters
+  Generator get generator => _generator;
+
+  @visibleForTesting
+  // TODO(srawlins): Remove when https://github.com/dart-lang/linter/issues/2706
+  // is fixed.
+  // ignore: unnecessary_getters_setters
+  set generator(Generator newGenerator) => _generator = newGenerator;
+
   /// An asynchronous factory method that builds Dartdoc's file writers
   /// and returns a Dartdoc object with them.
   @Deprecated('Prefer fromContext() instead')
@@ -158,10 +169,8 @@ class Dartdoc {
 
   /// Asynchronous factory method that builds Dartdoc with a generator
   /// determined by the given context.
-  static Future<Dartdoc> fromContext(
-    DartdocGeneratorOptionContext context,
-    PackageBuilder packageBuilder,
-  ) async {
+  static Future<Dartdoc> fromContext(DartdocGeneratorOptionContext context,
+      PackageBuilder packageBuilder) async {
     Generator generator;
     switch (context.format) {
       case 'html':
@@ -194,18 +203,15 @@ class Dartdoc {
         'in ${seconds.toStringAsFixed(1)} seconds');
     stopwatch.reset();
 
-    var generator = this.generator;
-    if (generator != null) {
-      // Create the out directory.
-      if (!_outputDir.exists) _outputDir.create();
+    // Create the out directory.
+    if (!_outputDir.exists) _outputDir.create();
 
-      var writer = DartdocFileWriter(_outputDir.path, config.resourceProvider);
-      await generator.generate(packageGraph, writer);
+    var writer = DartdocFileWriter(_outputDir.path, config.resourceProvider);
+    await generator.generate(packageGraph, writer);
 
-      _writtenFiles.addAll(writer.writtenFiles);
-      if (config.validateLinks && _writtenFiles.isNotEmpty) {
-        _validateLinks(packageGraph, _outputDir.path);
-      }
+    _writtenFiles.addAll(writer.writtenFiles);
+    if (config.validateLinks && _writtenFiles.isNotEmpty) {
+      _validateLinks(packageGraph, _outputDir.path);
     }
 
     var warnings = packageGraph.packageWarningCounter.warningCount;

lib/options.dart

@@ -44,6 +44,7 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext {
   String get relCanonicalPrefix =>
       optionSet['relCanonicalPrefix'].valueAt(context);
 
+  /// The 'templatesDir' Dartdoc option if one was specified; otherwise `null`.
   String get templatesDir => optionSet['templatesDir'].valueAt(context);
 
   // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.

lib/src/generator/dartdoc_generator_backend.dart

@@ -8,8 +8,6 @@ import 'package:dartdoc/src/generator/generator_frontend.dart';
 import 'package:dartdoc/src/generator/generator_utils.dart' as generator_util;
 import 'package:dartdoc/src/generator/template_data.dart';
 import 'package:dartdoc/src/generator/templates.dart';
-import 'package:dartdoc/src/generator/templates.runtime_renderers.dart';
-import 'package:dartdoc/src/mustachio/renderer_base.dart';
 import 'package:dartdoc/src/warnings.dart';
 import 'package:path/path.dart' as path show Context;
 
@@ -60,16 +58,15 @@ class DartdocGeneratorBackendOptions implements TemplateOptions {
 }
 
 class SidebarGenerator<T extends TemplateData> {
-  final Template template;
-  final RenderFunction<T> renderFunction;
+  final String Function(T context) renderFunction;
   final Map<Documentable, String> _renderCache = {};
 
-  SidebarGenerator(this.template, this.renderFunction);
+  SidebarGenerator(this.renderFunction);
 
   // Retrieve the render for a specific key, or generate it using the given
   // template data if you need.
   String getRenderFor(Documentable key, T templateData) {
-    return _renderCache[key] ??= renderFunction(templateData, template);
+    return _renderCache[key] ??= renderFunction(templateData);
   }
 }
 
@@ -86,10 +83,9 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
   DartdocGeneratorBackend(
       DartdocGeneratorBackendOptions options, this.templates, this._pathContext)
       : options = options ?? DartdocGeneratorBackendOptions._defaults(),
-        sidebarForLibrary = SidebarGenerator(
-            templates.sidebarLibraryTemplate, renderSidebarForLibrary),
-        sidebarForContainer = SidebarGenerator(
-            templates.sidebarContainerTemplate, renderSidebarForContainer);
+        sidebarForLibrary = SidebarGenerator(templates.renderSidebarForLibrary),
+        sidebarForContainer =
+            SidebarGenerator(templates.renderSidebarForContainer);
 
   /// Helper method to bind template data and emit the content to the writer.
   void write(
@@ -129,15 +125,15 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
   @override
   void generatePackage(FileWriter writer, PackageGraph graph, Package package) {
     TemplateData data = PackageTemplateData(options, graph, package);
-    var content = renderIndex(data, templates.indexTemplate);
+    var content = templates.renderIndex(data);
     write(writer, package.filePath, data, content);
   }
 
   @override
   void generateCategory(
       FileWriter writer, PackageGraph packageGraph, Category category) {
     TemplateData data = CategoryTemplateData(options, packageGraph, category);
-    var content = renderCategory(data, templates.categoryTemplate);
+    var content = templates.renderCategory(data);
     write(writer, category.filePath, data, content);
   }
 
@@ -146,7 +142,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       FileWriter writer, PackageGraph packageGraph, Library lib) {
     TemplateData data = LibraryTemplateData(
         options, packageGraph, lib, sidebarForLibrary.getRenderFor);
-    var content = renderLibrary(data, templates.libraryTemplate);
+    var content = templates.renderLibrary(data);
     write(writer, lib.filePath, data, content);
   }
 
@@ -155,7 +151,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       FileWriter writer, PackageGraph packageGraph, Library lib, Class clazz) {
     TemplateData data = ClassTemplateData(options, packageGraph, lib, clazz,
         sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
-    var content = renderClass(data, templates.classTemplate);
+    var content = templates.renderClass(data);
     write(writer, clazz.filePath, data, content);
   }
 
@@ -169,7 +165,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
         extension,
         sidebarForLibrary.getRenderFor,
         sidebarForContainer.getRenderFor);
-    var content = renderExtension(data, templates.extensionTemplate);
+    var content = templates.renderExtension(data);
     write(writer, extension.filePath, data, content);
   }
 
@@ -178,7 +174,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       FileWriter writer, PackageGraph packageGraph, Library lib, Mixin mixin) {
     TemplateData data = MixinTemplateData(options, packageGraph, lib, mixin,
         sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
-    var content = renderMixin(data, templates.mixinTemplate);
+    var content = templates.renderMixin(data);
     write(writer, mixin.filePath, data, content);
   }
 
@@ -187,7 +183,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       Library lib, Class clazz, Constructor constructor) {
     TemplateData data = ConstructorTemplateData(options, packageGraph, lib,
         clazz, constructor, sidebarForContainer.getRenderFor);
-    var content = renderConstructor(data, templates.constructorTemplate);
+    var content = templates.renderConstructor(data);
     write(writer, constructor.filePath, data, content);
   }
 
@@ -196,7 +192,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       FileWriter writer, PackageGraph packageGraph, Library lib, Enum eNum) {
     TemplateData data = EnumTemplateData(options, packageGraph, lib, eNum,
         sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
-    var content = renderEnum(data, templates.enumTemplate);
+    var content = templates.renderEnum(data);
     write(writer, eNum.filePath, data, content);
   }
 
@@ -205,7 +201,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       Library lib, ModelFunction function) {
     TemplateData data = FunctionTemplateData(
         options, packageGraph, lib, function, sidebarForLibrary.getRenderFor);
-    var content = renderFunction(data, templates.functionTemplate);
+    var content = templates.renderFunction(data);
     write(writer, function.filePath, data, content);
   }
 
@@ -214,7 +210,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       Container clazz, Method method) {
     TemplateData data = MethodTemplateData(options, packageGraph, lib, clazz,
         method, sidebarForContainer.getRenderFor);
-    var content = renderMethod(data, templates.methodTemplate);
+    var content = templates.renderMethod(data);
     write(writer, method.filePath, data, content);
   }
 
@@ -228,7 +224,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       Library lib, Container clazz, Field property) {
     TemplateData data = PropertyTemplateData(options, packageGraph, lib, clazz,
         property, sidebarForContainer.getRenderFor);
-    var content = renderProperty(data, templates.propertyTemplate);
+    var content = templates.renderProperty(data);
     write(writer, property.filePath, data, content);
   }
 
@@ -237,8 +233,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       Library lib, TopLevelVariable property) {
     TemplateData data = TopLevelPropertyTemplateData(
         options, packageGraph, lib, property, sidebarForLibrary.getRenderFor);
-    var content =
-        renderTopLevelProperty(data, templates.topLevelPropertyTemplate);
+    var content = templates.renderTopLevelProperty(data);
     write(writer, property.filePath, data, content);
   }
 
@@ -252,7 +247,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
       Library lib, Typedef typeDef) {
     TemplateData data = TypedefTemplateData(
         options, packageGraph, lib, typeDef, sidebarForLibrary.getRenderFor);
-    var content = renderTypedef(data, templates.typeDefTemplate);
+    var content = templates.renderTypedef(data);
     write(writer, typeDef.filePath, data, content);
   }
 

lib/src/generator/generator_frontend.dart

@@ -29,7 +29,8 @@ class GeneratorFrontEnd implements Generator {
     _generatorBackend.generateSearchIndex(writer, indexElements);
   }
 
-  // Traverses the package graph and collects elements for the search index.
+  /// Traverses the package graph and generates documentation for all contained
+  /// elements.
   void _generateDocs(PackageGraph packageGraph, FileWriter writer,
       List<Indexable> indexAccumulator) {
     if (packageGraph == null) return;

lib/src/generator/html_generator.dart

@@ -4,6 +4,7 @@
 
 library dartdoc.html_generator;
 
+import 'package:analyzer/file_system/file_system.dart';
 import 'package:dartdoc/options.dart';
 import 'package:dartdoc/src/generator/dartdoc_generator_backend.dart';
 import 'package:dartdoc/src/generator/generator.dart';
@@ -12,14 +13,17 @@ import 'package:dartdoc/src/generator/html_resources.g.dart' as resources;
 import 'package:dartdoc/src/generator/resource_loader.dart';
 import 'package:dartdoc/src/generator/template_data.dart';
 import 'package:dartdoc/src/generator/templates.dart';
-import 'package:dartdoc/src/generator/templates.runtime_renderers.dart';
 import 'package:dartdoc/src/model/package.dart';
 import 'package:dartdoc/src/model/package_graph.dart';
 import 'package:path/path.dart' as path show Context;
 
-Future<Generator> initHtmlGenerator(
-    DartdocGeneratorOptionContext context) async {
-  var templates = await Templates.fromContext(context);
+/// Creates a [Generator] with an [HtmlGeneratorBackend] backend.
+///
+/// [forceRuntimeTemplates] should only be given [true] during tests.
+Future<Generator> initHtmlGenerator(DartdocGeneratorOptionContext context,
+    {bool forceRuntimeTemplates = false}) async {
+  var templates = await Templates.fromContext(context,
+      forceRuntimeTemplates: forceRuntimeTemplates);
   var options = DartdocGeneratorBackendOptions.fromContext(context);
   var backend = HtmlGeneratorBackend(
       options, templates, context.resourceProvider.pathContext);
@@ -37,14 +41,14 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend {
     super.generatePackage(writer, graph, package);
     // We have to construct the data again. This only happens once per package.
     TemplateData data = PackageTemplateData(options, graph, package);
-    var content = renderError(data, templates.errorTemplate);
+    var content = templates.renderError(data);
     write(writer, '__404error.html', data, content);
   }
 
   @override
   Future<void> generateAdditionalFiles(
       FileWriter writer, PackageGraph graph) async {
-    await _copyResources(writer);
+    await _copyResources(writer, graph.resourceProvider);
     if (options.favicon != null) {
       // Allow overwrite of favicon.
       var bytes =
@@ -57,17 +61,18 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend {
     }
   }
 
-  Future<void> _copyResources(FileWriter writer) async {
+  Future<void> _copyResources(
+      FileWriter writer, ResourceProvider resourceProvider) async {
     for (var resourcePath in resources.resource_names) {
       if (!resourcePath.startsWith(_dartdocResourcePrefix)) {
         throw StateError('Resource paths must start with '
             '$_dartdocResourcePrefix, encountered $resourcePath');
       }
       var destFileName = resourcePath.substring(_dartdocResourcePrefix.length);
-      var destFilePath = writer.resourceProvider.pathContext
-          .join('static-assets', destFileName);
+      var destFilePath =
+          resourceProvider.pathContext.join('static-assets', destFileName);
       writer.writeBytes(destFilePath,
-          await writer.resourceProvider.loadResourceAsBytes(resourcePath));
+          await resourceProvider.loadResourceAsBytes(resourcePath));
     }
   }
 

lib/src/generator/markdown_generator.dart

@@ -8,13 +8,15 @@ 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/generator/templates.runtime_renderers.dart';
 import 'package:dartdoc/src/model/package.dart';
 import 'package:dartdoc/src/model/package_graph.dart';
 import 'package:path/path.dart' as path show Context;
 
-Future<Generator> initMarkdownGenerator(
-    DartdocGeneratorOptionContext context) async {
+/// Creates a [Generator] with an [MarkdownGeneratorBackend] backend.
+///
+/// [forceRuntimeTemplates] should only be given [true] during tests.
+Future<Generator> initMarkdownGenerator(DartdocGeneratorOptionContext context,
+    {bool forceRuntimeTemplates = false}) async {
   var templates = await Templates.fromContext(context);
   var options = DartdocGeneratorBackendOptions.fromContext(context);
   var backend = MarkdownGeneratorBackend(
@@ -33,7 +35,7 @@ class MarkdownGeneratorBackend extends DartdocGeneratorBackend {
     super.generatePackage(writer, graph, package);
     // We have to construct the data again. This only happens once per package.
     TemplateData data = PackageTemplateData(options, graph, package);
-    var content = renderError(data, templates.errorTemplate);
+    var content = templates.renderError(data);
     write(writer, '__404error.md', data, content);
   }
 }

lib/src/generator/resource_loader.dart

@@ -32,6 +32,11 @@ extension ResourceLoader on ResourceProvider {
     return getFile(uri.toFilePath());
   }
 
+  Future<Folder> getResourceFolder(String path) async {
+    var uri = await resolveResourceUri(Uri.parse(path));
+    return getFolder(uri.toFilePath());
+  }
+
   /// Helper function for resolving to a non-relative, non-package URI.
   @visibleForTesting
   Future<Uri> resolveResourceUri(Uri uri) {