From d50b10eeb59880dec075ef688bea8706d0f40ce2 Mon Sep 17 00:00:00 2001 From: Jonathan Koren Date: Fri, 14 Feb 2020 07:31:17 -0800 Subject: [PATCH 1/2] Create Markdown generator backend --- lib/dartdoc.dart | 6 ++-- lib/src/generator/markdown_generator.dart | 35 +++++++++++++++++++++++ 2 files changed, 38 insertions(+), 3 deletions(-) create mode 100644 lib/src/generator/markdown_generator.dart diff --git a/lib/dartdoc.dart b/lib/dartdoc.dart index 0e76ae5508..1f491ae46f 100644 --- a/lib/dartdoc.dart +++ b/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 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}'); diff --git a/lib/src/generator/markdown_generator.dart b/lib/src/generator/markdown_generator.dart new file mode 100644 index 0000000000..4af8820a87 --- /dev/null +++ b/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 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); + } +} From 9a77044618af697a6c822894934d42e0ae1b2a5e Mon Sep 17 00:00:00 2001 From: Jonathan Koren Date: Fri, 14 Feb 2020 08:34:15 -0800 Subject: [PATCH 2/2] Load markdown templates Note we need to maintain enumerated lists of partials in order to build resource URIs. --- lib/src/generator/templates.dart | 51 ++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/lib/src/generator/templates.dart b/lib/src/generator/templates.dart index 875328d99a..2fbae1fe62 100644 --- a/lib/src/generator/templates.dart +++ b/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 = [ +// 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 = [ 'callable', 'callable_multiline', 'categorization', @@ -42,6 +44,27 @@ const _partials = [ 'accessor_setter', ]; +const _partials_md = [ + '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 _partials; + + factory _DefaultTemplatesLoader.create(String format) { + List 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> loadPartials() async { - var partials = {}; + var templates = {}; 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 headerPaths, List footerPaths, List footerTextPaths}) async { - return _create(_DefaultTemplatesLoader(format), + return _create(_DefaultTemplatesLoader.create(format), headerPaths: headerPaths, footerPaths: footerPaths, footerTextPaths: footerTextPaths);