Add a resources-dir option (#2857)

Author: srawlins

lib/options.dart

@@ -51,12 +51,15 @@ 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.
   @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

lib/src/dartdoc_options.dart

@@ -1543,6 +1543,8 @@ Future<List<DartdocOption>> createDartdocOptions(
         help:
             'A list of package names to place first when grouping libraries in '
             'packages. Unmentioned packages are sorted after these.'),
+    DartdocOptionArgOnly<String>('resourcesDir', null, resourceProvider,
+        help: "An absolute path to dartdoc's resources directory.", hide: true),
     DartdocOptionArgOnly<bool>('sdkDocs', false, resourceProvider,
         help: 'Generate ONLY the docs for the Dart SDK.'),
     DartdocOptionArgSynth<String>('sdkDir',

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<T extends TemplateData> {

lib/src/generator/html_generator.dart

@@ -51,26 +51,28 @@ 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,
       );
     }
   }
 
   Future<void> _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';
 }

lib/src/generator/html_resources.g.dart

@@ -1,11 +1,11 @@
 // WARNING: This file is auto-generated. Do not edit.
 
 const List<String> 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',
 ];

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);
     }

tool/builder.dart

@@ -12,22 +12,25 @@ String _resourcesFile(Iterable<String> packagePaths) => '''
 // WARNING: This file is auto-generated. Do not edit.
 
 const List<String> 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<void> build(BuildStep buildStep) async {
-    var packagePaths = <String>[];
-    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')),