Move html templates, support loading templates by format (#2140)

Author: jdkoren

lib/src/html/html_generator.dart

@@ -11,7 +11,8 @@ import 'package:dartdoc/src/generator.dart';
 import 'package:dartdoc/src/generator_frontend.dart';
 import 'package:dartdoc/src/html/html_generator_backend.dart';
 
-Future<Generator> initHtmlGenerator(GeneratorContext context) async {
+Future<Generator> initHtmlGenerator(
+    DartdocGeneratorOptionContext context) async {
   var backend = await HtmlGeneratorBackend.fromContext(context);
   return GeneratorFrontEnd(backend);
 }

lib/src/html/html_generator_backend.dart

@@ -46,7 +46,7 @@ class HtmlGeneratorBackend implements GeneratorBackend {
   final Templates _templates;
 
   static Future<HtmlGeneratorBackend> fromContext(
-      GeneratorContext context) async {
+      DartdocGeneratorOptionContext context) async {
     Templates templates = await Templates.fromContext(context);
     // TODO(jcollins-g): Rationalize based on GeneratorContext all the way down
     // through the generators.

lib/src/html/templates.dart

@@ -41,25 +41,6 @@ const _partials = <String>[
   'accessor_setter',
 ];
 
-const _requiredTemplates = <String>[
-  '404error.html',
-  'category.html',
-  'class.html',
-  'constant.html',
-  'constructor.html',
-  'enum.html',
-  'extension.html',
-  'function.html',
-  'index.html',
-  'library.html',
-  'method.html',
-  'mixin.html',
-  'property.html',
-  'top_level_constant.html',
-  'top_level_property.html',
-  'typedef.html',
-];
-
 const String _headerPlaceholder = '{{! header placeholder }}';
 const String _footerPlaceholder = '{{! footer placeholder }}';
 const String _footerTextPlaceholder = '{{! footer-text placeholder }}';
@@ -97,34 +78,41 @@ abstract class _TemplatesLoader {
   Future<String> loadTemplate(String name);
 }
 
+/// Loads default templates included in the Dartdoc program.
 class _DefaultTemplatesLoader extends _TemplatesLoader {
+  final String _format;
+
+  _DefaultTemplatesLoader(this._format);
+
   @override
   Future<Map<String, String>> loadPartials() async {
     var partials = <String, String>{};
-    for (String partial in _partials) {
-      var uri = 'package:dartdoc/templates/_$partial.html';
-      partials[partial] = await loader.loadAsString(uri);
+    for (String name in _partials) {
+      var uri = 'package:dartdoc/templates/$_format/_$name.$_format';
+      partials[name] = await loader.loadAsString(uri);
     }
     return partials;
   }
 
   @override
   Future<String> loadTemplate(String name) =>
-      loader.loadAsString('package:dartdoc/templates/$name');
+      loader.loadAsString('package:dartdoc/templates/$_format/$name.$_format');
 }
 
+/// Loads templates from a specified Directory.
 class _DirectoryTemplatesLoader extends _TemplatesLoader {
   final Directory _directory;
+  final String _format;
 
-  _DirectoryTemplatesLoader(this._directory);
+  _DirectoryTemplatesLoader(this._directory, this._format);
 
   @override
   Future<Map<String, String>> loadPartials() async {
     var partials = <String, String>{};
 
     for (File file in _directory.listSync().whereType<File>()) {
       var basename = path.basename(file.path);
-      if (basename.startsWith('_') && basename.endsWith('.html')) {
+      if (basename.startsWith('_') && basename.endsWith('.$_format')) {
         var content = file.readAsString();
         var partialName = basename.substring(1, basename.lastIndexOf('.'));
         partials[partialName] = await content;
@@ -135,7 +123,10 @@ class _DirectoryTemplatesLoader extends _TemplatesLoader {
 
   @override
   Future<String> loadTemplate(String name) {
-    var file = File(path.join(_directory.path, name));
+    var file = File(path.join(_directory.path, '$name.$_format'));
+    if (!file.existsSync()) {
+      throw DartdocFailure('Missing required template file: $name.$_format');
+    }
     return file.readAsString();
   }
 }
@@ -158,51 +149,41 @@ class Templates {
   final Template topLevelPropertyTemplate;
   final Template typeDefTemplate;
 
-  static Future<Templates> fromContext(GeneratorContext context) {
+  static Future<Templates> fromContext(DartdocGeneratorOptionContext context) {
     String templatesDir = context.templatesDir;
     if (templatesDir != null) {
-      return fromDirectory(Directory(templatesDir),
+      return fromDirectory(Directory(templatesDir), context.format,
           headerPaths: context.header,
           footerPaths: context.footer,
           footerTextPaths: context.footerTextPaths);
     } else {
-      return createDefault(
+      return createDefault(context.format,
           headerPaths: context.header,
           footerPaths: context.footer,
           footerTextPaths: context.footerTextPaths);
     }
   }
 
-  static Future<Templates> createDefault(
+  static Future<Templates> createDefault(String format,
       {List<String> headerPaths,
       List<String> footerPaths,
       List<String> footerTextPaths}) async {
-    return _create(_DefaultTemplatesLoader(),
+    return _create(_DefaultTemplatesLoader(format),
         headerPaths: headerPaths,
         footerPaths: footerPaths,
         footerTextPaths: footerTextPaths);
   }
 
-  static Future<Templates> fromDirectory(Directory dir,
+  static Future<Templates> fromDirectory(Directory dir, String format,
       {List<String> headerPaths,
       List<String> footerPaths,
       List<String> footerTextPaths}) async {
-    await _checkRequiredTemplatesExist(dir);
-    return _create(_DirectoryTemplatesLoader(dir),
+    return _create(_DirectoryTemplatesLoader(dir, format),
         headerPaths: headerPaths,
         footerPaths: footerPaths,
         footerTextPaths: footerTextPaths);
   }
 
-  static void _checkRequiredTemplatesExist(Directory dir) {
-    for (var name in _requiredTemplates) {
-      var file = File(path.join(dir.path, name));
-      if (!file.existsSync()) {
-        throw DartdocFailure('Missing required template file: "$name"');
-      }
-    }
-  }
-
   static Future<Templates> _create(_TemplatesLoader templatesLoader,
       {List<String> headerPaths,
       List<String> footerPaths,
@@ -224,24 +205,22 @@ class Templates {
       return Template(templateContents, partialResolver: _partial);
     }
 
-    var indexTemplate = await _loadTemplate('index.html');
-    var libraryTemplate = await _loadTemplate('library.html');
-    var categoryTemplate = await _loadTemplate('category.html');
-    var classTemplate = await _loadTemplate('class.html');
-    var extensionTemplate = await _loadTemplate('extension.html');
-    var enumTemplate = await _loadTemplate('enum.html');
-    var functionTemplate = await _loadTemplate('function.html');
-    var methodTemplate = await _loadTemplate('method.html');
-    var constructorTemplate = await _loadTemplate('constructor.html');
-    var errorTemplate = await _loadTemplate('404error.html');
-    var propertyTemplate = await _loadTemplate('property.html');
-    var constantTemplate = await _loadTemplate('constant.html');
-    var topLevelConstantTemplate =
-        await _loadTemplate('top_level_constant.html');
-    var topLevelPropertyTemplate =
-        await _loadTemplate('top_level_property.html');
-    var typeDefTemplate = await _loadTemplate('typedef.html');
-    var mixinTemplate = await _loadTemplate('mixin.html');
+    var indexTemplate = await _loadTemplate('index');
+    var libraryTemplate = await _loadTemplate('library');
+    var categoryTemplate = await _loadTemplate('category');
+    var classTemplate = await _loadTemplate('class');
+    var extensionTemplate = await _loadTemplate('extension');
+    var enumTemplate = await _loadTemplate('enum');
+    var functionTemplate = await _loadTemplate('function');
+    var methodTemplate = await _loadTemplate('method');
+    var constructorTemplate = await _loadTemplate('constructor');
+    var errorTemplate = await _loadTemplate('404error');
+    var propertyTemplate = await _loadTemplate('property');
+    var constantTemplate = await _loadTemplate('constant');
+    var topLevelConstantTemplate = await _loadTemplate('top_level_constant');
+    var topLevelPropertyTemplate = await _loadTemplate('top_level_property');
+    var typeDefTemplate = await _loadTemplate('typedef');
+    var mixinTemplate = await _loadTemplate('mixin');
 
     return Templates._(
         indexTemplate,

lib/templates/404error.html renamed to lib/templates/html/404error.html

@@ -20,7 +20,8 @@ import 'src/utils.dart' as utils;
 
 // Init a generator without a GeneratorContext and with the default file writer.
 Future<Generator> _initGeneratorForTest() async {
-  var backend = HtmlGeneratorBackend(null, await Templates.createDefault());
+  var backend =
+      HtmlGeneratorBackend(null, await Templates.createDefault('html'));
   return GeneratorFrontEnd(backend);
 }
 
@@ -29,7 +30,7 @@ void main() {
     Templates templates;
 
     setUp(() async {
-      templates = await Templates.createDefault();
+      templates = await Templates.createDefault('html');
     });
 
     test('index html', () {

lib/templates/_accessor_getter.html renamed to lib/templates/html/_accessor_getter.html

@@ -10,8 +10,8 @@ import 'package:test/test.dart';
 void main() {
   group('Resource Loader', () {
     test('load from packages', () async {
-      var contents =
-          await loader.loadAsString('package:dartdoc/templates/index.html');
+      var contents = await loader
+          .loadAsString('package:dartdoc/templates/html/index.html');
       expect(contents, isNotNull);
     });