Adds a flag, --link-to-external, to interlink packages, SDK together (#1678)

Author: jcollins-g

README.md

@@ -103,12 +103,21 @@ generates docs.
 ```yaml
 dartdoc:
   categoryOrder: ["First Category", "Second Category"]
+  linkTo:
+    url: "https://my.dartdocumentationsite.org/dev/%v%"
 ```
 
-Unrecognized options will be ignored.  For now, there's only one supported option:
+Unrecognized options will be ignored.  Supported options:
 
   * **categoryOrder**:  Specify the order of categories, below, for display in the sidebar and
     the package page.
+  * **linkTo**:  For other packages depending on this one, if this map is defined those packages
+    will use the settings here to control how hyperlinks to the package are generated.
+    This will override the default for packages hosted on pub.dartlang.org.
+    * url:  A string indicating the base URL for documentation of this package.  The following
+      strings will be substituted in to complete the URL:
+      * `%n%`: The name of this package, as defined in pubspec.yaml.
+      * `%v%`: The version of this package as defined in pubspec.yaml.
 
 The following are experimental options whose semantics are in flux and may be buggy.  If you
 use one, please keep a close eye on the changing semantics.  In general, paths are relative

bin/dartdoc.dart

@@ -66,7 +66,7 @@ main(List<String> arguments) async {
   startLogging(config);
 
   Directory outputDir = new Directory(config.output);
-  logInfo("Generating documentation for '${config.packageMeta}' into "
+  logInfo("Generating documentation for '${config.topLevelPackageMeta}' into "
       "${outputDir.absolute.path}${Platform.pathSeparator}");
 
   Dartdoc dartdoc = await Dartdoc.withDefaultGenerators(config, outputDir);

lib/dartdoc.dart

@@ -85,8 +85,8 @@ class Dartdoc extends PackageBuilder {
           new AnalysisErrorInfoImpl(errorsResult.errors, errorsResult.lineInfo);
       List<_Error> errors = [info]
           .expand((AnalysisErrorInfo info) {
-            return info.errors.map((error) =>
-                new _Error(error, info.lineInfo, config.packageMeta.dir.path));
+            return info.errors.map((error) => new _Error(
+                error, info.lineInfo, config.topLevelPackageMeta.dir.path));
           })
           .where((_Error error) => error.isError)
           .toList()
@@ -103,8 +103,8 @@ class Dartdoc extends PackageBuilder {
 
     List<_Error> errors = errorInfos
         .expand((AnalysisErrorInfo info) {
-          return info.errors.map((error) =>
-              new _Error(error, info.lineInfo, config.packageMeta.dir.path));
+          return info.errors.map((error) => new _Error(
+              error, info.lineInfo, config.topLevelPackageMeta.dir.path));
         })
         .where((_Error error) => error.isError)
         // TODO(jcollins-g): remove after conversion to analysis driver
@@ -172,7 +172,8 @@ class Dartdoc extends PackageBuilder {
       throw new DartdocFailure("dartdoc encountered errors while processing");
     }
 
-    return new DartdocResults(config.packageMeta, packageGraph, outputDir);
+    return new DartdocResults(
+        config.topLevelPackageMeta, packageGraph, outputDir);
   }
 
   /// Warn on file paths.

lib/src/dartdoc_options.dart

@@ -842,12 +842,25 @@ class DartdocOptionContext {
   // ignore: unused_element
   String get _input => optionSet['input'].valueAt(context);
   String get inputDir => optionSet['inputDir'].valueAt(context);
+  bool get linkToExternal => optionSet['linkTo']['external'].valueAt(context);
+  String get linkToExternalUrl =>
+      optionSet['linkTo']['externalUrl'].valueAt(context);
+
+  /// _linkToHosted is only used to construct synthetic options.
+  // ignore: unused_element
+  String get _linkToHosted => optionSet['linkTo']['hosted'].valueAt(context);
+
+  /// _linkToUrl is only used to construct synthetic options.
+  // ignore: unused_element
+  String get _linkToUrl => optionSet['linkTo']['url'].valueAt(context);
   String get output => optionSet['output'].valueAt(context);
-  List<String> get packageOrder => optionSet['packageOrder'].valueAt(context);
   PackageMeta get packageMeta => optionSet['packageMeta'].valueAt(context);
+  List<String> get packageOrder => optionSet['packageOrder'].valueAt(context);
   bool get sdkDocs => optionSet['sdkDocs'].valueAt(context);
   String get sdkDir => optionSet['sdkDir'].valueAt(context);
   bool get showWarnings => optionSet['showWarnings'].valueAt(context);
+  PackageMeta get topLevelPackageMeta =>
+      optionSet['topLevelPackageMeta'].valueAt(context);
   bool get useCategories => optionSet['useCategories'].valueAt(context);
   bool get validateLinks => optionSet['validateLinks'].valueAt(context);
   bool get verboseWarnings => optionSet['verboseWarnings'].valueAt(context);
@@ -936,9 +949,59 @@ Future<List<DartdocOption>> createDartdocOptions() async {
         help: 'Path to source directory (with override if --sdk-docs)',
         isDir: true,
         mustExist: true),
+    new DartdocOptionSet('linkTo')
+      ..addAll([
+        new DartdocOptionArgOnly<bool>('external', false,
+            help: 'Allow links to be generated for packages outside this one.',
+            negatable: true),
+        new DartdocOptionSynthetic<String>('externalUrl',
+            (DartdocOptionSynthetic option, Directory dir) {
+          String url = option.parent['url'].valueAt(dir);
+          if (url != null) {
+            return url;
+          }
+          String hostedAt =
+              option.parent.parent['packageMeta'].valueAt(dir).hostedAt;
+          if (hostedAt != null) {
+            Map<String, String> hostMap = option.parent['hosted'].valueAt(dir);
+            if (hostMap.containsKey(hostedAt)) return hostMap[hostedAt];
+          }
+          return '';
+        }, help: 'Url to use for this particular package.'),
+        new DartdocOptionArgOnly<Map<String, String>>(
+            'hosted',
+            {
+              'pub.dartlang.org':
+                  'https://pub.dartlang.org/documentation/%n%/%v%'
+            },
+            help: 'Specify URLs for hosted pub packages'),
+        new DartdocOptionFileOnly<String>('url', null,
+            help: 'Use external linkage for this package, with this base url'),
+      ]),
     new DartdocOptionArgOnly<String>('output', pathLib.join('doc', 'api'),
         isDir: true, help: 'Path to output directory.'),
-    new DartdocOptionSynthetic<PackageMeta>('packageMeta',
+    new DartdocOptionSynthetic<PackageMeta>(
+      'packageMeta',
+      (DartdocOptionSynthetic option, Directory dir) {
+        PackageMeta packageMeta = new PackageMeta.fromDir(dir);
+        if (packageMeta == null) {
+          throw new DartdocOptionError(
+              'Unable to determine package for directory: ${dir.path}');
+        }
+        return packageMeta;
+      },
+    ),
+    new DartdocOptionArgOnly<List<String>>('packageOrder', [],
+        help:
+            'A list of package names to place first when grouping libraries in packages. '
+            'Unmentioned categories are sorted after these.'),
+    new DartdocOptionArgOnly<bool>('sdkDocs', false,
+        help: 'Generate ONLY the docs for the Dart SDK.', negatable: false),
+    new DartdocOptionArgOnly<String>('sdkDir', defaultSdkDir.absolute.path,
+        help: 'Path to the SDK directory.', isDir: true, mustExist: true),
+    new DartdocOptionArgOnly<bool>('showWarnings', false,
+        help: 'Display all warnings.', negatable: false),
+    new DartdocOptionSynthetic<PackageMeta>('topLevelPackageMeta',
         (DartdocOptionSynthetic option, Directory dir) {
       PackageMeta packageMeta = new PackageMeta.fromDir(
           new Directory(option.parent['inputDir'].valueAt(dir)));
@@ -952,16 +1015,6 @@ Future<List<DartdocOption>> createDartdocOptions() async {
       }
       return packageMeta;
     }, help: 'PackageMeta object for the default package.'),
-    new DartdocOptionArgOnly<List<String>>('packageOrder', [],
-        help:
-            'A list of package names to place first when grouping libraries in packages. '
-            'Unmentioned categories are sorted after these.'),
-    new DartdocOptionArgOnly<bool>('sdkDocs', false,
-        help: 'Generate ONLY the docs for the Dart SDK.', negatable: false),
-    new DartdocOptionArgOnly<String>('sdkDir', defaultSdkDir.absolute.path,
-        help: 'Path to the SDK directory', isDir: true, mustExist: true),
-    new DartdocOptionArgOnly<bool>('showWarnings', false,
-        help: 'Display all warnings.', negatable: false),
     new DartdocOptionArgOnly<bool>('useCategories', true,
         help: 'Display categories in the sidebar of packages',
         negatable: false),

lib/src/io_utils.dart

@@ -126,7 +126,7 @@ class SubprocessLauncher {
   /// output of the executable continuously and fail on non-zero exit codes.
   /// It will also parse any valid JSON objects (one per line) it encounters
   /// on stdout/stderr, and return them.  Returns null if no JSON objects
-  /// were encountered.
+  /// were encountered, or if DRY_RUN is set to 1 in the execution environment.
   ///
   /// Makes running programs in grinder similar to set -ex for bash, even on
   /// Windows (though some of the bashisms will no longer make sense).
@@ -157,8 +157,6 @@ class SubprocessLauncher {
       return line.split('\n');
     }
 
-    Process process = await Process.start(executable, arguments,
-        workingDirectory: workingDirectory, environment: environment);
     stderr.write('$prefix+ ');
     if (workingDirectory != null) stderr.write('(cd "$workingDirectory" && ');
     if (environment != null) {
@@ -183,6 +181,11 @@ class SubprocessLauncher {
     }
     if (workingDirectory != null) stderr.write(')');
     stderr.write('\n');
+
+    if (Platform.environment.containsKey('DRY_RUN')) return null;
+
+    Process process = await Process.start(executable, arguments,
+        workingDirectory: workingDirectory, environment: environment);
     _printStream(process.stdout, stdout, prefix: prefix, filter: jsonCallback);
     _printStream(process.stderr, stderr, prefix: prefix, filter: jsonCallback);
     await process.exitCode;