Skip to content

Commit 20992ea

Browse files
authored
Use Mustachio AOT compiler for default templates (#2677)
1 parent 58f7181 commit 20992ea

18 files changed

+1509
-318
lines changed

lib/dartdoc.dart

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ class DartdocFileWriter implements FileWriter {
115115
/// Generates Dart documentation for all public Dart libraries in the given
116116
/// directory.
117117
class Dartdoc {
118-
final Generator generator;
118+
Generator _generator;
119119
final PackageBuilder packageBuilder;
120120
final DartdocOptionContext config;
121121
final Set<String> _writtenFiles = {};
@@ -125,12 +125,23 @@ class Dartdoc {
125125
final StreamController<String> _onCheckProgress =
126126
StreamController(sync: true);
127127

128-
Dartdoc._(this.config, this.generator, this.packageBuilder) {
128+
Dartdoc._(this.config, this._generator, this.packageBuilder) {
129129
_outputDir = config.resourceProvider
130130
.getFolder(config.resourceProvider.pathContext.absolute(config.output))
131131
..create();
132132
}
133133

134+
// TODO(srawlins): Remove when https://github.com/dart-lang/linter/issues/2706
135+
// is fixed.
136+
// ignore: unnecessary_getters_setters
137+
Generator get generator => _generator;
138+
139+
@visibleForTesting
140+
// TODO(srawlins): Remove when https://github.com/dart-lang/linter/issues/2706
141+
// is fixed.
142+
// ignore: unnecessary_getters_setters
143+
set generator(Generator newGenerator) => _generator = newGenerator;
144+
134145
/// An asynchronous factory method that builds Dartdoc's file writers
135146
/// and returns a Dartdoc object with them.
136147
@Deprecated('Prefer fromContext() instead')
@@ -195,18 +206,15 @@ class Dartdoc {
195206
'in ${seconds.toStringAsFixed(1)} seconds');
196207
stopwatch.reset();
197208

198-
var generator = this.generator;
199-
if (generator != null) {
200-
// Create the out directory.
201-
if (!_outputDir.exists) _outputDir.create();
209+
// Create the out directory.
210+
if (!_outputDir.exists) _outputDir.create();
202211

203-
var writer = DartdocFileWriter(_outputDir.path, config.resourceProvider);
204-
await generator.generate(packageGraph, writer);
212+
var writer = DartdocFileWriter(_outputDir.path, config.resourceProvider);
213+
await generator.generate(packageGraph, writer);
205214

206-
_writtenFiles.addAll(writer.writtenFiles);
207-
if (config.validateLinks && _writtenFiles.isNotEmpty) {
208-
_validateLinks(packageGraph, _outputDir.path);
209-
}
215+
_writtenFiles.addAll(writer.writtenFiles);
216+
if (config.validateLinks && _writtenFiles.isNotEmpty) {
217+
_validateLinks(packageGraph, _outputDir.path);
210218
}
211219

212220
var warnings = packageGraph.packageWarningCounter.warningCount;

lib/options.dart

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext {
4444
String get relCanonicalPrefix =>
4545
optionSet['relCanonicalPrefix'].valueAt(context);
4646

47+
/// The 'templatesDir' Dartdoc option if one was specified; otherwise `null`.
4748
String get templatesDir => optionSet['templatesDir'].valueAt(context);
4849

4950
// TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration.

lib/src/generator/dartdoc_generator_backend.dart

Lines changed: 25 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,13 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5+
import 'package:analyzer/file_system/file_system.dart';
56
import 'package:dartdoc/dartdoc.dart';
67
import 'package:dartdoc/options.dart';
78
import 'package:dartdoc/src/generator/generator_frontend.dart';
89
import 'package:dartdoc/src/generator/generator_utils.dart' as generator_util;
910
import 'package:dartdoc/src/generator/template_data.dart';
1011
import 'package:dartdoc/src/generator/templates.dart';
11-
import 'package:dartdoc/src/generator/templates.runtime_renderers.dart';
12-
import 'package:dartdoc/src/mustachio/renderer_base.dart';
1312
import 'package:dartdoc/src/warnings.dart';
1413
import 'package:path/path.dart' as path show Context;
1514

@@ -60,16 +59,15 @@ class DartdocGeneratorBackendOptions implements TemplateOptions {
6059
}
6160

6261
class SidebarGenerator<T extends TemplateData> {
63-
final Template template;
64-
final RenderFunction<T> renderFunction;
62+
final String Function(T context) renderFunction;
6563
final Map<Documentable, String> _renderCache = {};
6664

67-
SidebarGenerator(this.template, this.renderFunction);
65+
SidebarGenerator(this.renderFunction);
6866

6967
// Retrieve the render for a specific key, or generate it using the given
7068
// template data if you need.
7169
String getRenderFor(Documentable key, T templateData) {
72-
return _renderCache[key] ??= renderFunction(templateData, template);
70+
return _renderCache[key] ??= renderFunction(templateData);
7371
}
7472
}
7573

@@ -81,15 +79,16 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
8179
sidebarForLibrary;
8280
final SidebarGenerator<TemplateDataWithContainer<Documentable>>
8381
sidebarForContainer;
82+
final ResourceProvider resourceProvider;
8483
final path.Context _pathContext;
8584

86-
DartdocGeneratorBackend(
87-
DartdocGeneratorBackendOptions options, this.templates, this._pathContext)
85+
DartdocGeneratorBackend(DartdocGeneratorBackendOptions options,
86+
this.templates, this.resourceProvider)
8887
: options = options ?? DartdocGeneratorBackendOptions._defaults(),
89-
sidebarForLibrary = SidebarGenerator(
90-
templates.sidebarLibraryTemplate, renderSidebarForLibrary),
91-
sidebarForContainer = SidebarGenerator(
92-
templates.sidebarContainerTemplate, renderSidebarForContainer);
88+
sidebarForLibrary = SidebarGenerator(templates.renderSidebarForLibrary),
89+
sidebarForContainer =
90+
SidebarGenerator(templates.renderSidebarForContainer),
91+
_pathContext = resourceProvider.pathContext;
9392

9493
/// Helper method to bind template data and emit the content to the writer.
9594
void write(
@@ -129,15 +128,15 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
129128
@override
130129
void generatePackage(FileWriter writer, PackageGraph graph, Package package) {
131130
TemplateData data = PackageTemplateData(options, graph, package);
132-
var content = renderIndex(data, templates.indexTemplate);
131+
var content = templates.renderIndex(data);
133132
write(writer, package.filePath, data, content);
134133
}
135134

136135
@override
137136
void generateCategory(
138137
FileWriter writer, PackageGraph packageGraph, Category category) {
139138
TemplateData data = CategoryTemplateData(options, packageGraph, category);
140-
var content = renderCategory(data, templates.categoryTemplate);
139+
var content = templates.renderCategory(data);
141140
write(writer, category.filePath, data, content);
142141
}
143142

@@ -146,7 +145,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
146145
FileWriter writer, PackageGraph packageGraph, Library lib) {
147146
TemplateData data = LibraryTemplateData(
148147
options, packageGraph, lib, sidebarForLibrary.getRenderFor);
149-
var content = renderLibrary(data, templates.libraryTemplate);
148+
var content = templates.renderLibrary(data);
150149
write(writer, lib.filePath, data, content);
151150
}
152151

@@ -155,7 +154,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
155154
FileWriter writer, PackageGraph packageGraph, Library lib, Class clazz) {
156155
TemplateData data = ClassTemplateData(options, packageGraph, lib, clazz,
157156
sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
158-
var content = renderClass(data, templates.classTemplate);
157+
var content = templates.renderClass(data);
159158
write(writer, clazz.filePath, data, content);
160159
}
161160

@@ -169,7 +168,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
169168
extension,
170169
sidebarForLibrary.getRenderFor,
171170
sidebarForContainer.getRenderFor);
172-
var content = renderExtension(data, templates.extensionTemplate);
171+
var content = templates.renderExtension(data);
173172
write(writer, extension.filePath, data, content);
174173
}
175174

@@ -178,7 +177,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
178177
FileWriter writer, PackageGraph packageGraph, Library lib, Mixin mixin) {
179178
TemplateData data = MixinTemplateData(options, packageGraph, lib, mixin,
180179
sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
181-
var content = renderMixin(data, templates.mixinTemplate);
180+
var content = templates.renderMixin(data);
182181
write(writer, mixin.filePath, data, content);
183182
}
184183

@@ -187,7 +186,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
187186
Library lib, Class clazz, Constructor constructor) {
188187
TemplateData data = ConstructorTemplateData(options, packageGraph, lib,
189188
clazz, constructor, sidebarForContainer.getRenderFor);
190-
var content = renderConstructor(data, templates.constructorTemplate);
189+
var content = templates.renderConstructor(data);
191190
write(writer, constructor.filePath, data, content);
192191
}
193192

@@ -196,7 +195,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
196195
FileWriter writer, PackageGraph packageGraph, Library lib, Enum eNum) {
197196
TemplateData data = EnumTemplateData(options, packageGraph, lib, eNum,
198197
sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
199-
var content = renderEnum(data, templates.enumTemplate);
198+
var content = templates.renderEnum(data);
200199
write(writer, eNum.filePath, data, content);
201200
}
202201

@@ -205,7 +204,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
205204
Library lib, ModelFunction function) {
206205
TemplateData data = FunctionTemplateData(
207206
options, packageGraph, lib, function, sidebarForLibrary.getRenderFor);
208-
var content = renderFunction(data, templates.functionTemplate);
207+
var content = templates.renderFunction(data);
209208
write(writer, function.filePath, data, content);
210209
}
211210

@@ -214,7 +213,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
214213
Container clazz, Method method) {
215214
TemplateData data = MethodTemplateData(options, packageGraph, lib, clazz,
216215
method, sidebarForContainer.getRenderFor);
217-
var content = renderMethod(data, templates.methodTemplate);
216+
var content = templates.renderMethod(data);
218217
write(writer, method.filePath, data, content);
219218
}
220219

@@ -228,7 +227,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
228227
Library lib, Container clazz, Field property) {
229228
TemplateData data = PropertyTemplateData(options, packageGraph, lib, clazz,
230229
property, sidebarForContainer.getRenderFor);
231-
var content = renderProperty(data, templates.propertyTemplate);
230+
var content = templates.renderProperty(data);
232231
write(writer, property.filePath, data, content);
233232
}
234233

@@ -237,8 +236,7 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
237236
Library lib, TopLevelVariable property) {
238237
TemplateData data = TopLevelPropertyTemplateData(
239238
options, packageGraph, lib, property, sidebarForLibrary.getRenderFor);
240-
var content =
241-
renderTopLevelProperty(data, templates.topLevelPropertyTemplate);
239+
var content = templates.renderTopLevelProperty(data);
242240
write(writer, property.filePath, data, content);
243241
}
244242

@@ -252,11 +250,10 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
252250
Library lib, Typedef typeDef) {
253251
TemplateData data = TypedefTemplateData(
254252
options, packageGraph, lib, typeDef, sidebarForLibrary.getRenderFor);
255-
var content = renderTypedef(data, templates.typeDefTemplate);
253+
var content = templates.renderTypedef(data);
256254
write(writer, typeDef.filePath, data, content);
257255
}
258256

259257
@override
260-
Future<void> generateAdditionalFiles(
261-
FileWriter writer, PackageGraph graph) async {}
258+
Future<void> generateAdditionalFiles(FileWriter writer) async {}
262259
}

lib/src/generator/generator_frontend.dart

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ class GeneratorFrontEnd implements Generator {
1919
Future<void> generate(PackageGraph packageGraph, FileWriter writer) async {
2020
var indexElements = <Indexable>[];
2121
_generateDocs(packageGraph, writer, indexElements);
22-
await _generatorBackend.generateAdditionalFiles(writer, packageGraph);
22+
await _generatorBackend.generateAdditionalFiles(writer);
2323

2424
var categories = indexElements
2525
.whereType<Categorization>()
@@ -29,7 +29,8 @@ class GeneratorFrontEnd implements Generator {
2929
_generatorBackend.generateSearchIndex(writer, indexElements);
3030
}
3131

32-
// Traverses the package graph and collects elements for the search index.
32+
/// Traverses the package graph and generates documentation for all contained
33+
/// elements.
3334
void _generateDocs(PackageGraph packageGraph, FileWriter writer,
3435
List<Indexable> indexAccumulator) {
3536
if (packageGraph == null) return;
@@ -338,5 +339,5 @@ abstract class GeneratorBackend {
338339
FileWriter writer, PackageGraph graph, Library library, Typedef typedef);
339340

340341
/// Emit files not specific to a Dart language element.
341-
Future<void> generateAdditionalFiles(FileWriter writer, PackageGraph graph);
342+
Future<void> generateAdditionalFiles(FileWriter writer);
342343
}

lib/src/generator/html_generator.dart

Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
library dartdoc.html_generator;
66

7+
import 'package:analyzer/file_system/file_system.dart';
78
import 'package:dartdoc/options.dart';
89
import 'package:dartdoc/src/generator/dartdoc_generator_backend.dart';
910
import 'package:dartdoc/src/generator/generator.dart';
@@ -12,45 +13,45 @@ import 'package:dartdoc/src/generator/html_resources.g.dart' as resources;
1213
import 'package:dartdoc/src/generator/resource_loader.dart';
1314
import 'package:dartdoc/src/generator/template_data.dart';
1415
import 'package:dartdoc/src/generator/templates.dart';
15-
import 'package:dartdoc/src/generator/templates.runtime_renderers.dart';
1616
import 'package:dartdoc/src/model/package.dart';
1717
import 'package:dartdoc/src/model/package_graph.dart';
18-
import 'package:path/path.dart' as path show Context;
1918

20-
Future<Generator> initHtmlGenerator(
21-
DartdocGeneratorOptionContext context) async {
22-
var templates = await Templates.fromContext(context);
19+
/// Creates a [Generator] with an [HtmlGeneratorBackend] backend.
20+
///
21+
/// [forceRuntimeTemplates] should only be given [true] during tests.
22+
Future<Generator> initHtmlGenerator(DartdocGeneratorOptionContext context,
23+
{bool forceRuntimeTemplates = false}) async {
24+
var templates = await Templates.fromContext(context,
25+
forceRuntimeTemplates: forceRuntimeTemplates);
2326
var options = DartdocGeneratorBackendOptions.fromContext(context);
24-
var backend = HtmlGeneratorBackend(
25-
options, templates, context.resourceProvider.pathContext);
27+
var backend =
28+
HtmlGeneratorBackend(options, templates, context.resourceProvider);
2629
return GeneratorFrontEnd(backend);
2730
}
2831

2932
/// Generator backend for html output.
3033
class HtmlGeneratorBackend extends DartdocGeneratorBackend {
3134
HtmlGeneratorBackend(DartdocGeneratorBackendOptions options,
32-
Templates templates, path.Context pathContext)
33-
: super(options, templates, pathContext);
35+
Templates templates, ResourceProvider resourceProvider)
36+
: super(options, templates, resourceProvider);
3437

3538
@override
3639
void generatePackage(FileWriter writer, PackageGraph graph, Package package) {
3740
super.generatePackage(writer, graph, package);
3841
// We have to construct the data again. This only happens once per package.
3942
TemplateData data = PackageTemplateData(options, graph, package);
40-
var content = renderError(data, templates.errorTemplate);
43+
var content = templates.renderError(data);
4144
write(writer, '__404error.html', data, content);
4245
}
4346

4447
@override
45-
Future<void> generateAdditionalFiles(
46-
FileWriter writer, PackageGraph graph) async {
48+
Future<void> generateAdditionalFiles(FileWriter writer) async {
4749
await _copyResources(writer);
4850
if (options.favicon != null) {
4951
// Allow overwrite of favicon.
50-
var bytes =
51-
writer.resourceProvider.getFile(options.favicon).readAsBytesSync();
52+
var bytes = resourceProvider.getFile(options.favicon).readAsBytesSync();
5253
writer.writeBytes(
53-
graph.resourceProvider.pathContext.join('static-assets', 'favicon.png'),
54+
resourceProvider.pathContext.join('static-assets', 'favicon.png'),
5455
bytes,
5556
allowOverwrite: true,
5657
);
@@ -64,10 +65,10 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend {
6465
'$_dartdocResourcePrefix, encountered $resourcePath');
6566
}
6667
var destFileName = resourcePath.substring(_dartdocResourcePrefix.length);
67-
var destFilePath = writer.resourceProvider.pathContext
68-
.join('static-assets', destFileName);
68+
var destFilePath =
69+
resourceProvider.pathContext.join('static-assets', destFileName);
6970
writer.writeBytes(destFilePath,
70-
await writer.resourceProvider.loadResourceAsBytes(resourcePath));
71+
await resourceProvider.loadResourceAsBytes(resourcePath));
7172
}
7273
}
7374

0 commit comments

Comments
 (0)