From baab7a4e69277733ea6531a2e08219163312fe08 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Mon, 29 Nov 2021 12:13:33 -0800 Subject: [PATCH 1/3] Add a resources-dir option --- lib/options.dart | 3 +++ lib/src/dartdoc_options.dart | 2 ++ .../generator/dartdoc_generator_backend.dart | 8 ++++-- lib/src/generator/html_generator.dart | 26 ++++++++++--------- lib/src/generator/html_resources.g.dart | 14 +++++----- test/html_generator_test.dart | 3 +-- tool/builder.dart | 17 +++++++----- 7 files changed, 43 insertions(+), 30 deletions(-) diff --git a/lib/options.dart b/lib/options.dart index 9af65023ab..fc65a2b70d 100644 --- a/lib/options.dart +++ b/lib/options.dart @@ -57,6 +57,9 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext { // TODO(jdkoren): duplicated temporarily so that GeneratorContext is enough for configuration. @override bool get useBaseHref => optionSet['useBaseHref'].valueAt(context); + + /// The 'resourcesDir' Dartdoc option if one was specified; otherwise `null`. + String /*?*/ get resourcesDir => optionSet['resourcesDir'].valueAt(context); } class DartdocProgramOptionContext extends DartdocGeneratorOptionContext diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index 0c6760fd6b..778b667b1a 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -1543,6 +1543,8 @@ Future> createDartdocOptions( help: 'A list of package names to place first when grouping libraries in ' 'packages. Unmentioned packages are sorted after these.'), + DartdocOptionArgOnly('resourcesDir', null, resourceProvider, + help: "An absolute path to dartdoc's resources directory.", hide: true), DartdocOptionArgOnly('sdkDocs', false, resourceProvider, help: 'Generate ONLY the docs for the Dart SDK.'), DartdocOptionArgSynth('sdkDir', diff --git a/lib/src/generator/dartdoc_generator_backend.dart b/lib/src/generator/dartdoc_generator_backend.dart index 7ab32db4cf..6b24a5f155 100644 --- a/lib/src/generator/dartdoc_generator_backend.dart +++ b/lib/src/generator/dartdoc_generator_backend.dart @@ -38,6 +38,8 @@ class DartdocGeneratorBackendOptions implements TemplateOptions { @override final String customInnerFooterText; + final String /*?*/ resourcesDir; + DartdocGeneratorBackendOptions.fromContext( DartdocGeneratorOptionContext context) : relCanonicalPrefix = context.relCanonicalPrefix, @@ -47,7 +49,8 @@ class DartdocGeneratorBackendOptions implements TemplateOptions { useBaseHref = context.useBaseHref, customHeaderContent = context.header, customFooterContent = context.footer, - customInnerFooterText = context.footerText; + customInnerFooterText = context.footerText, + resourcesDir = context.resourcesDir; DartdocGeneratorBackendOptions._defaults() : relCanonicalPrefix = null, @@ -57,7 +60,8 @@ class DartdocGeneratorBackendOptions implements TemplateOptions { useBaseHref = false, customHeaderContent = '', customFooterContent = '', - customInnerFooterText = ''; + customInnerFooterText = '', + resourcesDir = null; } class SidebarGenerator { diff --git a/lib/src/generator/html_generator.dart b/lib/src/generator/html_generator.dart index 32a0db6bff..f8f482f934 100644 --- a/lib/src/generator/html_generator.dart +++ b/lib/src/generator/html_generator.dart @@ -51,7 +51,7 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend { // Allow overwrite of favicon. var bytes = resourceProvider.getFile(options.favicon).readAsBytesSync(); writer.writeBytes( - resourceProvider.pathContext.join('static-assets', 'favicon.png'), + _pathJoin('static-assets', 'favicon.png'), bytes, allowOverwrite: true, ); @@ -59,18 +59,20 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend { } Future _copyResources(FileWriter writer) async { - for (var resourcePath in resources.resourceNames) { - if (!resourcePath.startsWith(_dartdocResourcePrefix)) { - throw StateError('Resource paths must start with ' - '$_dartdocResourcePrefix, encountered $resourcePath'); - } - var destFileName = resourcePath.substring(_dartdocResourcePrefix.length); - var destFilePath = - resourceProvider.pathContext.join('static-assets', destFileName); - writer.writeBytes(destFilePath, - await resourceProvider.loadResourceAsBytes(resourcePath)); + var resourcesDir = options.resourcesDir ?? + (await resourceProvider.getResourceFolder(_dartdocResourcePrefix)).path; + for (var resourceFileName in resources.resourceNames) { + var destinationPath = _pathJoin('static-assets', resourceFileName); + var sourcePath = _pathJoin(resourcesDir, resourceFileName); + writer.writeBytes( + destinationPath, + resourceProvider.getFile(sourcePath).readAsBytesSync(), + ); } } - static const _dartdocResourcePrefix = 'package:dartdoc/resources/'; + String _pathJoin(String a, String b) => + resourceProvider.pathContext.join(a, b); + + static const _dartdocResourcePrefix = 'package:dartdoc/resources'; } diff --git a/lib/src/generator/html_resources.g.dart b/lib/src/generator/html_resources.g.dart index 0815edeae9..b4517a9ee4 100644 --- a/lib/src/generator/html_resources.g.dart +++ b/lib/src/generator/html_resources.g.dart @@ -1,11 +1,11 @@ // WARNING: This file is auto-generated. Do not edit. const List resourceNames = [ - 'package:dartdoc/resources/favicon.png', - 'package:dartdoc/resources/github.css', - 'package:dartdoc/resources/highlight.pack.js', - 'package:dartdoc/resources/play_button.svg', - 'package:dartdoc/resources/readme.md', - 'package:dartdoc/resources/script.js', - 'package:dartdoc/resources/styles.css' + 'favicon.png', + 'github.css', + 'highlight.pack.js', + 'play_button.svg', + 'readme.md', + 'script.js', + 'styles.css', ]; diff --git a/test/html_generator_test.dart b/test/html_generator_test.dart index 00c16d37ea..9141dd52be 100644 --- a/test/html_generator_test.dart +++ b/test/html_generator_test.dart @@ -125,8 +125,7 @@ void main() { .getFolder(pathContext.join(outputPath, 'static-assets')); expect(output, doesExist); - for (var resource in resourceNames.map((r) => - pathContext.relative(Uri.parse(r).path, from: 'dartdoc/resources'))) { + for (var resource in resourceNames) { expect(resourceProvider.getFile(pathContext.join(output.path, resource)), doesExist); } diff --git a/tool/builder.dart b/tool/builder.dart index c9d1aad05a..e3522dbd03 100644 --- a/tool/builder.dart +++ b/tool/builder.dart @@ -12,22 +12,25 @@ String _resourcesFile(Iterable packagePaths) => ''' // WARNING: This file is auto-generated. Do not edit. const List resourceNames = [ -${packagePaths.map((p) => " '$p'").join(',\n')} +${packagePaths.map((p) => " '$p',").join('\n')} ]; '''; class ResourceBuilder implements Builder { final BuilderOptions builderOptions; + ResourceBuilder(this.builderOptions); - static final _allResources = Glob('lib/resources/**'); + static const _resourcesPath = 'lib/resources'; + @override Future build(BuildStep buildStep) async { - var packagePaths = []; - await for (AssetId asset in buildStep.findAssets(_allResources)) { - packagePaths.add(asset.uri.toString()); - } - packagePaths.sort(); + var resourceAssets = + await buildStep.findAssets(Glob('$_resourcesPath/**')).toList(); + var packagePaths = [ + for (var asset in resourceAssets) + path.url.relative(asset.path, from: _resourcesPath), + ]..sort(); await buildStep.writeAsString( AssetId(buildStep.inputId.package, path.url.join('lib', 'src', 'generator', 'html_resources.g.dart')), From e60a17035a328e0d5e2493c1335684e90f352cc2 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Wed, 1 Dec 2021 08:48:04 -0800 Subject: [PATCH 2/3] typo nit --- lib/options.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/options.dart b/lib/options.dart index fc65a2b70d..faed3844b3 100644 --- a/lib/options.dart +++ b/lib/options.dart @@ -51,7 +51,7 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext { String get relCanonicalPrefix => optionSet['relCanonicalPrefix'].valueAt(context); - /// The 'templatesDir' Dartdoc option if one was specified; otherwise `null`. + /// 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. From 74a84e0d86a72507081405cbc8092887e0d9529b Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Wed, 1 Dec 2021 10:43:00 -0800 Subject: [PATCH 3/3] typo nit --- lib/options.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/options.dart b/lib/options.dart index faed3844b3..e4e904e70a 100644 --- a/lib/options.dart +++ b/lib/options.dart @@ -58,7 +58,7 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext { @override bool get useBaseHref => optionSet['useBaseHref'].valueAt(context); - /// The 'resourcesDir' Dartdoc option if one was specified; otherwise `null`. + /// The 'resourcesDir' dartdoc option if one was specified; otherwise `null`. String /*?*/ get resourcesDir => optionSet['resourcesDir'].valueAt(context); }