Add example and use it in the dartdoc package.

Author: jcollins-g

README.md

@@ -163,6 +163,19 @@ Unrecognized options will be ignored.  Supported options:
         No branch is considered to be "stable".
       * `%n%`: The name of this package, as defined in pubspec.yaml.
       * `%v%`: The version of this package as defined in pubspec.yaml.
+  * **linkToSource**: Generate links to a source code repository based on given templates and
+    revision information.
+    * **excludes**: A list of directories to exclude from processing source links.
+    * **root**: The directory to consider the 'root' for inserting relative paths into the template.
+      Source code outside the root directory will not be linked.
+    * **uriTemplate**: A template to substitute revision and file path information.  If revision
+      is present in the template but not specified, or if root is not specified, dartdoc will
+      throw an exception.  To hard-code a revision, don't specify it with `%r%`.
+      
+      The following strings will be substituted in to complete the URL:
+      * `%f%`:  Relative path of file to the repository root
+      * `%r%`:  Revision
+      * `%l%`:  Line number
   * **warnings**:  Specify otherwise ignored or set-to-error warnings to simply warn.  See the lists
     of valid warnings in the command line help for `--errors`, `--warnings`, and `--ignore`.
 
@@ -391,6 +404,35 @@ other elements on the page, since those may change in future versions of Dartdoc
 If `--auto-include-dependencies` flag is provided, dartdoc tries to automatically add
 all the used libraries, even from other packages, to the list of the documented libraries.
 
+### Using link-to-source
+
+The source linking feature in dartdoc is a little tricky to use, since pub packages do not actually
+include enough information to link back to source code and that's the context in which documentation
+is generated for the pub site.  This means that for now, it must be manually specified in
+dartdoc_options.yaml what revision to use.  It is currently recommended practice to
+specify a revision in dartdoc_options.yaml that points to the same revision as your public package.
+If you're using a documentation staging system outside of Dart's pub site, override the template and
+revision on the command line with the head revision number.  You can use the branch name,
+but generated docs will generate locations that may start drifting with further changes to the branch.
+
+Example dartdoc_options.yaml:
+```yaml
+link-to-source:
+  root: '.'
+  uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v0.28.0/%f%#L%l%'
+```
+
+Example staging command line:
+```bash
+pub global run dartdoc --link-to-source-root '.' --link-to-source-revision 6fac6f770d271312c88e8ae881861702a9a605be --link-to-source-uri-template 'https://github.com/dart-lang/dartdoc/blob/%r%/%f#L%l%'
+```
+
+This gets more complicated with `--auto-include-dependencies` as these command line flags
+will override all settings from individual packages.  In that case, to preserve
+source links from third party packages it may be necessary to generate
+dartdoc_options.yaml options for each package you are intending to add source links
+to yourself.
+
 ## Issues and bugs
 
 Please file reports on the [GitHub Issue Tracker][].  Issues are labeled with

dartdoc_options.yaml

@@ -0,0 +1,4 @@
+dartdoc:
+  linkToSource:
+    root: '.'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v0.28.0/%f%#L%l%'

lib/src/source_linker.dart

@@ -13,18 +13,18 @@ final uriTemplateRegexp = new RegExp(r'(%[frl]%)');
 
 abstract class SourceLinkerOptionContext implements DartdocOptionContextBase {
   List<String> get linkToSourceExcludes =>
-      optionSet['link-to-source']['excludes'].valueAt(context);
+      optionSet['linkToSource']['excludes'].valueAt(context);
   String get linkToSourceRevision =>
-      optionSet['link-to-source']['revision'].valueAt(context);
+      optionSet['linkToSource']['revision'].valueAt(context);
   String get linkToSourceRoot =>
-      optionSet['link-to-source']['root'].valueAt(context);
+      optionSet['linkToSource']['root'].valueAt(context);
   String get linkToSourceUriTemplate =>
-      optionSet['link-to-source']['uriTemplate'].valueAt(context);
+      optionSet['linkToSource']['uriTemplate'].valueAt(context);
 }
 
 Future<List<DartdocOption>> createSourceLinkerOptions() async {
   return <DartdocOption>[
-    new DartdocOptionSet('link-to-source')
+    new DartdocOptionSet('linkToSource')
       ..addAll([
         new DartdocOptionArgFile<List<String>>('excludes', [],
             isDir: true,
@@ -65,11 +65,11 @@ class SourceLinker {
       String this.revision,
       String this.root,
       String this.uriTemplate}) {
-    assert(excludes != null, 'link-to-source-excludes can not be null');
+    assert(excludes != null, 'linkToSource excludes can not be null');
     if (revision != null || root != null || uriTemplate != null) {
       if (root == null || uriTemplate == null) {
         throw DartdocOptionError(
-            'link-to-source root and uriTemplate must both be specified to generate repository links');
+            'linkToSource root and uriTemplate must both be specified to generate repository links');
       }
       if (uriTemplate.contains('%r%') && revision == null) {
         throw DartdocOptionError(

testing/test_package/dartdoc_options.yaml

@@ -16,6 +16,6 @@ dartdoc:
       linux: ['/bin/sh', '-c', 'echo']
       windows: ['C:\\Windows\\System32\\cmd.exe', '/c', 'echo']
       description: 'Works on everything'
-  link-to-source:
+  linkToSource:
     root: '.'
     uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/master/testing/test_package/%f%#L%l%'

tool/grind.dart

@@ -779,10 +779,21 @@ Future<void> build() async {
   var launcher = new SubprocessLauncher('build');
   await launcher.runStreamed(sdkBin('pub'),
       ['run', 'build_runner', 'build', '--delete-conflicting-outputs']);
+
+  // TODO(jcollins-g): port to build system?
+  String version = _getPackageVersion();
+  File dartdoc_options = new File('dartdoc_options.yaml');
+  await dartdoc_options.writeAsString(
+'''dartdoc:
+  linkToSource:
+    root: '.'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v${version}/%f%#L%l%'
+''');
 }
 
 /// Paths in this list are relative to lib/.
 final _generated_files_list = <String>[
+  '../dartdoc_options.yaml',
   'src/html/resources.g.dart',
   'src/version.dart',
 ].map((s) => pathLib.joinAll(pathLib.posix.split(s)));
@@ -803,8 +814,7 @@ Future<void> checkBuild() async {
     }
   }
 
-  await launcher.runStreamed(sdkBin('pub'),
-      ['run', 'build_runner', 'build', '--delete-conflicting-outputs']);
+  await build();
   for (String relPath in _generated_files_list) {
     File newVersion = new File(pathLib.join('lib', relPath));
     if (!await newVersion.exists()) {