feat: support --example-path-prefix (#1302)

Author: chalin

bin/dartdoc.dart

@@ -139,6 +139,7 @@ main(List<String> arguments) async {
 
   initializeConfig(
       addCrossdart: addCrossdart,
+      examplePathPrefix: args['example-path-prefix'],
       includeSource: includeSource,
       inputDir: inputDir,
       sdkVersion: sdk.sdkVersion);
@@ -199,6 +200,8 @@ ArgParser _createArgsParser() {
   parser.addOption('hosted-url',
       help:
           'URL where the docs will be hosted (used to generate the sitemap).');
+  parser.addOption('example-path-prefix',
+      help: 'Prefix for @example paths. Default is project root.');
   parser.addOption('rel-canonical-prefix',
       help:
           'If provided, add a rel="canonical" prefixed with provided value. \n'

lib/dartdoc.dart

@@ -65,11 +65,13 @@ void initializeConfig(
     {Directory inputDir,
     String sdkVersion,
     bool addCrossdart: false,
+    String examplePathPrefix,
     bool includeSource: true}) {
   setConfig(
       inputDir: inputDir,
       sdkVersion: sdkVersion,
       addCrossdart: addCrossdart,
+      examplePathPrefix: examplePathPrefix,
       includeSource: includeSource);
 }
 

lib/src/config.dart

@@ -9,10 +9,11 @@ import 'dart:io';
 class Config {
   final Directory inputDir;
   final bool addCrossdart;
+  final String examplePathPrefix;
   final bool includeSource;
   final String sdkVersion;
   Config._(
-      this.inputDir, this.addCrossdart, this.includeSource, this.sdkVersion);
+      this.inputDir, this.addCrossdart, this.examplePathPrefix, this.includeSource, this.sdkVersion);
 }
 
 Config _config;
@@ -22,6 +23,7 @@ void setConfig(
     {Directory inputDir,
     String sdkVersion,
     bool addCrossdart: false,
+    String examplePathPrefix,
     bool includeSource: true}) {
-  _config = new Config._(inputDir, addCrossdart, includeSource, sdkVersion);
+  _config = new Config._(inputDir, addCrossdart, examplePathPrefix, includeSource, sdkVersion);
 }

lib/src/model.dart

@@ -1793,7 +1793,8 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     RegExp keyValueRE = new RegExp('(\\w+)=[\'"]?(\\S*)[\'"]?');
     Iterable<Match> matches = keyValueRE.allMatches(namedArgs);
     matches.forEach((match) {
-      args[match[1]] = match[2];
+      // Ignore optional quotes
+      args[match[1]] = match[2].replaceAll(new RegExp('[\'"]'), '');
     });
 
     // Compute 'file'
@@ -1806,7 +1807,7 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
       var ext = p.extension(src);
       file = p.join(dir, '$basename-$region$ext$fragExtension');
     }
-    args['file'] = file;
+    args['file'] = config.examplePathPrefix == null ? file : p.join(config.examplePathPrefix, file);
     return args;
   }
 }

test/compare_output_test.dart

@@ -50,6 +50,8 @@ void main() {
 
       var args = <String>[
         dartdocBin,
+        '--example-path-prefix',
+        'examples',
         '--no-include-source',
         '--output',
         tempDir.path
@@ -133,9 +135,14 @@ void main() {
         fail('dartdoc failed');
       }
 
-      if (!result.stderr
-          .contains(new RegExp(r'warning:.*file-does-not-exist\.js'))) {
-        fail('Missing warning for nonexistent @example: \nstdout: ${result.stdout} \nstderr: ${result.stderr}');
+      // Examples are reported as unfound because we (purposefully)
+      // did not use --example-path-prefix above.
+      final sep = '.'; // We don't care what the path separator character is
+      final firstUnfoundExample = new RegExp('warning: lib${sep}example.dart: '
+          '@example file not found.*test_package${sep}dog${sep}food.md');
+      if (!result.stderr.contains(firstUnfoundExample)) {
+        fail('Should warn about unfound @example files: \n'
+            'stdout:\n${result.stdout}\nstderr:\n${result.stderr}');
       }
     });
 
@@ -156,7 +163,6 @@ void main() {
         print(result.stderr);
         fail('dartdoc failed');
       }
-
     });
   }, onPlatform: {'windows': new Skip('Avoiding parsing git output')});
 }

testing/test_package/examples/dog_food-meat.txt.md renamed to testing/test_package/examples/dog/food-meat.txt.md

@@ -198,11 +198,10 @@ class ConstantCat implements Cat {
 
 /// implements [Cat], [E]
 ///
-/// {@example examples/dog_food}
-/// {@example examples/dog_food.txt region=meat}
+/// {@example dog/food}
+/// {@example dog/food.txt region=meat}
 ///
-/// {@example examples/test.dart region= lang=html}
-/// {@example examples/file-does-not-exist.js}
+/// {@example test.dart region= lang=html}
 class Dog implements Cat, E {
   String name;
 

testing/test_package/examples/dog_food.md renamed to testing/test_package/examples/dog/food.md

@@ -141,7 +141,6 @@ <h5><a href="ex/ex-library.html">ex</a></h5>
 A selection of dog flavors:</p><ul><li>beef</li><li>poultry</li></ul>
 <pre class="language-html prettyprint"><code class="language-html">&lt;h1&gt;Hello &lt;b&gt;World&lt;/b&gt;!&lt;/h1&gt;
 </code></pre>
-<p>{@example examples/file-does-not-exist.js}</p>
     </section>
 
     <section>