add support for a --footer-text flag (#1377)

* add support for a --footer-text flag

* update the changelog

Author: devoncarew

CHANGELOG.md

@@ -1,3 +1,8 @@
+## unreleased
+
+* added a new `--footer-text` command-line option, to allow adding additional
+  text in the package name and copyright section of the footer
+
 ## 0.10.0
 
 * fix canonicalization problems and related issues introduced or not addressed

bin/dartdoc.dart

@@ -72,6 +72,16 @@ main(List<String> arguments) async {
   List<String> includeExternals = args['include-external'] as List<String>;
 
   String url = args['hosted-url'];
+
+  List<String> headerFilePaths =
+      args['header'].map(_resolveTildePath).toList() as List<String>;
+  for (String headerFilePath in headerFilePaths) {
+    if (!new File(headerFilePath).existsSync()) {
+      stderr.write(" Error: unable to locate header file: ${headerFilePath}.");
+      exit(1);
+    }
+  }
+
   List<String> footerFilePaths =
       args['footer'].map(_resolveTildePath).toList() as List<String>;
   for (String footerFilePath in footerFilePaths) {
@@ -80,11 +90,13 @@ main(List<String> arguments) async {
       exit(1);
     }
   }
-  List<String> headerFilePaths =
-      args['header'].map(_resolveTildePath).toList() as List<String>;
-  for (String headerFilePath in footerFilePaths) {
-    if (!new File(headerFilePath).existsSync()) {
-      stderr.write(" Error: unable to locate header file: ${headerFilePath}.");
+
+  List<String> footerTextFilePaths =
+      args['footer-text'].map(_resolveTildePath).toList() as List<String>;
+  for (String footerFilePath in footerTextFilePaths) {
+    if (!new File(footerFilePath).existsSync()) {
+      stderr.write(
+          " Error: unable to locate footer-text file: ${footerFilePath}.");
       exit(1);
     }
   }
@@ -125,8 +137,10 @@ main(List<String> arguments) async {
       "${outputDir.absolute.path}${Platform.pathSeparator}");
   print('');
 
-  var generators = await initGenerators(
-      url, headerFilePaths, footerFilePaths, args['rel-canonical-prefix'],
+  var generators = await initGenerators(url, args['rel-canonical-prefix'],
+      headerFilePaths: headerFilePaths,
+      footerFilePaths: footerFilePaths,
+      footerTextFilePaths: footerTextFilePaths,
       faviconPath: args['favicon'],
       useCategories: args['use-categories'],
       prettyIndexJson: args['pretty-index-json']);
@@ -201,6 +215,10 @@ ArgParser _createArgsParser() {
       allowMultiple: true,
       splitCommas: true,
       help: 'paths to footer files containing HTML text.');
+  parser.addOption('footer-text',
+      allowMultiple: true,
+      splitCommas: true,
+      help: 'paths to footer-text files (optional text next to the copyright).');
   parser.addOption('exclude',
       allowMultiple: true, splitCommas: true, help: 'Library names to ignore.');
   parser.addOption('include',

lib/dartdoc.dart

@@ -47,9 +47,11 @@ const String version = '0.10.0';
 final String defaultOutDir = path.join('doc', 'api');
 
 /// Initialize and setup the generators.
-Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
-    List<String> footerFilePaths, String relCanonicalPrefix,
-    {String faviconPath,
+Future<List<Generator>> initGenerators(String url, String relCanonicalPrefix,
+    {List<String> headerFilePaths,
+    List<String> footerFilePaths,
+    List<String> footerTextFilePaths,
+    String faviconPath,
     bool useCategories: false,
     bool prettyIndexJson: false}) async {
   var options = new HtmlGeneratorOptions(
@@ -65,6 +67,7 @@ Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
       options: options,
       headers: headerFilePaths,
       footers: footerFilePaths,
+      footerTexts: footerTextFilePaths,
     )
   ];
 }

lib/src/html/html_generator.dart

@@ -46,9 +46,11 @@ class HtmlGenerator extends Generator {
   static Future<HtmlGenerator> create(
       {HtmlGeneratorOptions options,
       List<String> headers,
-      List<String> footers}) async {
-    var templates =
-        await Templates.create(headerPaths: headers, footerPaths: footers);
+      List<String> footers, List<String> footerTexts}) async {
+    var templates = await Templates.create(
+        headerPaths: headers,
+        footerPaths: footers,
+        footerTextPaths: footerTexts);
 
     return new HtmlGenerator._(
         options ?? new HtmlGeneratorOptions(), templates);

lib/src/html/templates.dart

@@ -33,33 +33,40 @@ const _partials = const <String>[
   'accessor_setter'
 ];
 
-Future<Map<String, String>> _loadPartials(
-    List<String> headerPaths, List<String> footerPaths) async {
+Future<Map<String, String>> _loadPartials(List<String> headerPaths,
+    List<String> footerPaths, List<String> footerTextPaths) async {
+  final String headerPlaceholder = '<!-- header placeholder -->';
+  final String footerPlaceholder = '<!-- footer placeholder -->';
+  final String footerTextPlaceholder = '<!-- footer-text placeholder -->';
+
   headerPaths ??= [];
   footerPaths ??= [];
+  footerTextPaths ??= [];
 
   var partials = <String, String>{};
 
   Future<String> _loadPartial(String templatePath) async {
     String template = await _getTemplateFile(templatePath);
-    if (templatePath.contains('_head') && headerPaths.isNotEmpty) {
+
+    if (templatePath.contains('_head')) {
       String headerValue = headerPaths
           .map((path) => new File(path).readAsStringSync())
           .join('\n');
-      template =
-          template.replaceAll('<!-- Header Placeholder -->', headerValue);
-      template =
-          template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
+      template = template.replaceAll(headerPlaceholder, headerValue);
     }
-    if (templatePath.contains('_footer') && footerPaths.isNotEmpty) {
+
+    if (templatePath.contains('_footer')) {
       String footerValue = footerPaths
           .map((path) => new File(path).readAsStringSync())
           .join('\n');
-      template =
-          template.replaceAll('<!-- Footer Placeholder -->', footerValue);
-      template =
-          template.replaceAll('  <!-- Do not remove placeholder -->\n', '');
+      template = template.replaceAll(footerPlaceholder, footerValue);
+
+      String footerTextValue = footerTextPaths
+          .map((path) => new File(path).readAsStringSync())
+          .join('\n');
+      template = template.replaceAll(footerTextPlaceholder, footerTextValue);
     }
+
     return template;
   }
 
@@ -88,8 +95,11 @@ class Templates {
   final TemplateRenderer typeDefTemplate;
 
   static Future<Templates> create(
-      {List<String> headerPaths, List<String> footerPaths}) async {
-    var partials = await _loadPartials(headerPaths, footerPaths);
+      {List<String> headerPaths,
+      List<String> footerPaths,
+      List<String> footerTextPaths}) async {
+    var partials =
+        await _loadPartials(headerPaths, footerPaths, footerTextPaths);
 
     String _partial(String name) {
       String partial = partials[name];

lib/templates/_footer.html

@@ -18,6 +18,8 @@
         <span class="copyright no-break">
           <a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
         </span>
+
+        <!-- footer-text placeholder -->
       </p>
     </div>
   </div>
@@ -28,8 +30,7 @@
 <script src="static-assets/prettify.js"></script>
 <script src="static-assets/URI.js"></script>
 <script src="static-assets/script.js"></script>
-<!-- Do not remove placeholder -->
-<!-- Footer Placeholder -->
+<!-- footer placeholder -->
 
 </body>
 

lib/templates/_head.html

@@ -23,8 +23,7 @@
   <link rel="stylesheet" href="static-assets/styles.css">
   <link rel="icon" href="static-assets/favicon.png">
 
-  <!-- Do not remove placeholder -->
-  <!-- Header Placeholder -->
+  <!-- header placeholder -->
 </head>
 
 <body>

test/compare_output_test.dart

@@ -8,7 +8,7 @@ import 'dart:convert';
 import 'dart:io';
 import 'dart:mirrors';
 
-import 'package:path/path.dart' as p;
+import 'package:path/path.dart' as path;
 import 'package:test/test.dart';
 
 const List<String> _filesToIgnore = const <String>['.DS_Store'];
@@ -21,16 +21,17 @@ Uri get _currentFileUri =>
     (reflect(main) as ClosureMirror).function.location.sourceUri;
 
 String get _testPackageDocsPath =>
-    p.fromUri(_currentFileUri.resolve('../testing/test_package_docs'));
+    path.fromUri(_currentFileUri.resolve('../testing/test_package_docs'));
 
 String get _testPackagePath =>
-    p.fromUri(_currentFileUri.resolve('../testing/test_package'));
+    path.fromUri(_currentFileUri.resolve('../testing/test_package'));
 
 void main() {
   group('compare outputs', () {
     Directory tempDir;
 
-    var dartdocBin = p.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
+    var dartdocBin =
+        path.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
 
     setUp(() {
       tempDir = Directory.systemTemp.createTempSync('dartdoc.test.');
@@ -99,8 +100,8 @@ void main() {
             'diff',
             '--no-index',
             '--no-color',
-            p.join(_testPackageDocsPath, k),
-            p.join(tempDir.path, k)
+            path.join(_testPackageDocsPath, k),
+            path.join(tempDir.path, k)
           ];
           result = Process.runSync(gitBinName, args);
           assert(result.exitCode != 0);
@@ -149,6 +150,34 @@ void main() {
       }
     });
 
+    test('--footer-text includes text', () {
+      String footerTextPath =
+          path.join(Directory.systemTemp.path, 'footer.txt');
+      new File(footerTextPath).writeAsStringSync(' footer text include ');
+
+      var args = <String>[
+        dartdocBin,
+        '--footer-text=${footerTextPath}',
+        '--include',
+        'ex',
+        '--output',
+        tempDir.path
+      ];
+
+      var result = Process.runSync(Platform.resolvedExecutable, args,
+          workingDirectory: _testPackagePath);
+
+      if (result.exitCode != 0) {
+        print(result.exitCode);
+        print(result.stdout);
+        print(result.stderr);
+        fail('dartdoc failed');
+      }
+
+      File outFile = new File(path.join(tempDir.path, 'index.html'));
+      expect(outFile.readAsStringSync(), contains('footer text include'));
+    });
+
     test('Check dartdoc generation with crossdart', () {
       var args = <String>[
         dartdocBin,
@@ -177,23 +206,23 @@ Map<String, String> _parseOutput(
     Match match = _nameStatusLineRegexp.firstMatch(line);
 
     var type = match[1];
-    var path = match[2];
+    var p = match[2];
 
-    if (_filesToIgnore.any((i) => p.basename(path) == i)) {
+    if (_filesToIgnore.any((i) => path.basename(p) == i)) {
       continue;
     }
 
     if (type == 'A') {
-      expect(p.isWithin(tempPath, path), isTrue,
-          reason: '`$path` should be within $tempPath');
-      path = p.relative(path, from: tempPath);
+      expect(path.isWithin(tempPath, p), isTrue,
+          reason: '`$p` should be within $tempPath');
+      p = path.relative(p, from: tempPath);
     } else {
-      expect(p.isWithin(sourcePath, path), isTrue,
-          reason: '`$path` should be within $sourcePath');
-      path = p.relative(path, from: sourcePath);
+      expect(path.isWithin(sourcePath, p), isTrue,
+          reason: '`$p` should be within $sourcePath');
+      p = path.relative(p, from: sourcePath);
     }
 
-    values[path] = type;
+    values[p] = type;
   }
 
   return values;

testing/test_package_docs/anonymous_library/anonymous_library-library.html

@@ -15,8 +15,6 @@
   <link rel="stylesheet" href="static-assets/styles.css">
   <link rel="icon" href="static-assets/favicon.png">
 
-  <!-- Do not remove placeholder -->
-  <!-- Header Placeholder -->
 </head>
 
 <body>
@@ -145,6 +143,7 @@ <h5>anonymous_library</h5>
         <span class="copyright no-break">
           <a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
         </span>
+
       </p>
     </div>
   </div>
@@ -155,8 +154,7 @@ <h5>anonymous_library</h5>
 <script src="static-assets/prettify.js"></script>
 <script src="static-assets/URI.js"></script>
 <script src="static-assets/script.js"></script>
-<!-- Do not remove placeholder -->
-<!-- Footer Placeholder -->
+
 
 </body>
 

testing/test_package_docs/anonymous_library/doesStuff.html

@@ -15,8 +15,6 @@
   <link rel="stylesheet" href="static-assets/styles.css">
   <link rel="icon" href="static-assets/favicon.png">
 
-  <!-- Do not remove placeholder -->
-  <!-- Header Placeholder -->
 </head>
 
 <body>
@@ -111,6 +109,7 @@ <h5><a href="anonymous_library/anonymous_library-library.html">anonymous_library
         <span class="copyright no-break">
           <a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
         </span>
+
       </p>
     </div>
   </div>
@@ -121,8 +120,7 @@ <h5><a href="anonymous_library/anonymous_library-library.html">anonymous_library
 <script src="static-assets/prettify.js"></script>
 <script src="static-assets/URI.js"></script>
 <script src="static-assets/script.js"></script>
-<!-- Do not remove placeholder -->
-<!-- Footer Placeholder -->
+
 
 </body>