feat(dart_doc_syncer): sync selected projects and other improvements

While maintain the ability to sync a single project by name,
this commit obviates the need to maintain a list of examples to sync.
Now dart_doc_syncer considers any example project with
a doc syncer data file (`.docsync.json`) as a potential candidate for
syncing.
Multiple projects can be synced at a time by use of
the `--match <path-regexp>` command-line option.

Other changes:

- Dry-run no longer forces verbosity.
- Updates to README.md file generation.
- docsync.json "schema" has changed:
  - `name` is now taken to represent the example folder name; e.g.,
'architecture'; it is omitted from the data file since its value can be
derived.
  - Added `title`, e.g. 'Architecture Overview'.
  - Added `docPart`, e.g. 'guide' (from 'guide/architecture').
  - `docHref` and `liveExampleHref` can now be relative URIs.
- New command-line flags (see command help for details):
  - An ng.io branch other than master can be specified.
  - `--keep-tmp`, `--no-push`.
- Tmp directory is set to ~/tmp if it exists instead of the script bin
folder.

Note, the behavior of `sync_add` has not be changed.

Author: chalin

bin/dart_doc_syncer.dart

@@ -9,34 +9,47 @@ import 'package:dart_doc_syncer/options.dart';
 /// Syncs an example application living in the angular.io repository to a
 /// dedicated repository that will contain a generated cleaned-up version.
 ///
-///    dart_doc_syncer [-h|-n|-v] [<exampleName> | <examplePath> <exampleRepo>]
+///    dart_doc_syncer [-h|options] [<exampleName> | <examplePath> <exampleRepo>]
 Future main(List<String> _args) async {
   var args = processArgs(_args);
-  Logger.root.level = dryRun || verbose ? Level.ALL : Level.WARNING;
+  Logger.root.level = options.verbose ? Level.ALL : Level.WARNING;
   Logger.root.onRecord.listen((LogRecord rec) {
     var msg = '${rec.message}';
-    if (!dryRun) msg = '${rec.level.name}: ${rec.time}: ' + msg;
+    if (!options.dryRun && !options.verbose)
+      msg = '${rec.level.name}: ${rec.time}: ' + msg;
     print(msg);
   });
 
-  var path, repositoryUri;
+  var exampleName, path, repositoryUri;
   switch (args.length) {
+    case 0:
+      if (options.match == null)
+        printUsageAndExit('No examples specified; name example or use --match');
+        // #NotReached
+      break;
     case 1:
-      var e2u = new Example2Uri(args[0]);
+      exampleName = args[0];
+      var e2u = new Example2Uri(exampleName);
       path = e2u.path;
       repositoryUri = e2u.repositoryUri;
       break;
     case 2:
       path = args[0];
       repositoryUri = args[1];
+      exampleName = getExampleName(path);
       break;
     default:
-      printUsageAndExit("Expected 1 or 2 arguments but found ${args.length}");
+      printUsageAndExit("Too many arguments (${args.length})");
     // #NotReached
   }
 
   final documentation = new DocumentationUpdater();
-  await documentation.updateRepository(path, repositoryUri);
-
-  print('Done updating $repositoryUri');
+  if (options.match == null) {
+    await documentation.updateRepository(path, repositoryUri,
+        clean: !options.keepTmp, exampleName: exampleName, push: options.push);
+    print('Done updating $repositoryUri');
+  } else {
+    await documentation.updateMatchingRepo(options.match,
+        clean: !options.keepTmp, push: options.push);
+  }
 }

bin/sync_all.dart

@@ -8,10 +8,10 @@ import 'package:logging/logging.dart';
 Future main(List<String> _args) async {
   processArgs(_args);
 
-  Logger.root.level = dryRun || verbose ? Level.ALL : Level.WARNING;
+  Logger.root.level = options.verbose ? Level.ALL : Level.WARNING;
   Logger.root.onRecord.listen((LogRecord rec) {
     var msg = '${rec.message}';
-    if (!dryRun) msg = '${rec.level.name}: ${rec.time}: ' + msg;
+    if (!options.dryRun && !options.verbose) msg = '${rec.level.name}: ${rec.time}: ' + msg;
     print(msg);
   });
 

lib/documentation_updater.dart

@@ -10,5 +10,9 @@ abstract class DocumentationUpdater {
   /// Updates [outRepositoryUri] based on the content of the example under
   /// [examplePath] in the angular.io repository.
   Future<bool> updateRepository(String examplePath, String outRepositoryUri,
-      {bool push, bool clean});
+      {String exampleName, bool push, bool clean});
+
+  /// Updates all example repositories containing a doc syncer data file
+  /// and whose path matches [re].
+  Future<int> updateMatchingRepo(RegExp re, {bool push, bool clean});
 }

lib/example2uri.dart

@@ -1,3 +1,5 @@
+import 'package:path/path.dart' as p;
+
 class Example2Uri {
   final String _exampleName;
 
@@ -8,3 +10,13 @@ class Example2Uri {
   String get repositoryUri =>
       '[email protected]:angular-examples/$_exampleName.git';
 }
+
+/// [path] is assumed to be of the form
+/// 'public/docs/_examples/<exampleName>/dart';
+/// returns <exampleName>.
+String getExampleName(String path) {
+  assert (p.basename(path) == 'dart');
+  var name = p.basename(p.dirname(path));
+  assert (name.isNotEmpty);
+  return name;
+}

lib/src/generate_doc.dart

@@ -50,7 +50,7 @@ Future assembleDocumentationExample(Directory snapshot, Directory out,
 /// Rewrites all files under the [path] directory by filtering out the
 /// documentation tags.
 Future _removeDocTagsFromApplication(String path) async {
-  if (Process.dryRun) return new Future.value(null);
+  if (Process.options.dryRun) return new Future.value(null);
 
   final files = await new Directory(path)
       .list(recursive: true)

lib/src/generate_gh_pages.dart

@@ -4,14 +4,13 @@ import 'dart:io';
 import 'package:path/path.dart' as p;
 
 import 'runner.dart' as Process; // TODO(chalin) tmp name to avoid code changes
-
-final String _basePath = p.dirname(Platform.script.path);
+import 'options.dart';
 
 /// Returns the path to the folder where the application assets have been
 /// generated.
 Future<String> generateApplication(
     Directory example, String exampleName) async {
-  final applicationPath = p.join(_basePath, '.tmp/${exampleName}_app');
+  final applicationPath = p.join(workDirPath, '${exampleName}_app');
 
   // Copy the application code into a seperate folder.
   await Process.run('cp', ['-a', p.join(example.path, '.'), applicationPath]);

lib/src/generate_readme.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:dart_doc_syncer/example2uri.dart';
 import 'package:logging/logging.dart';
 import 'package:path/path.dart' as p;
 
@@ -11,21 +12,21 @@ final Logger _logger = new Logger('generateReadme');
 
 /// Generates a README file for the example at [path].
 Future generateReadme(String path, {String angularIoPath}) async {
-  final syncDataFile = new File(p.join(path, '.docsync.json'));
+  final syncDataFile = new File(p.join(path, exampleConfigFileName));
   final dataExists = await syncDataFile.exists();
 
   final syncData = dataExists
       ? new SyncData.fromJson(await syncDataFile.readAsStringSync(),
           path: angularIoPath)
-      : new SyncData(name: p.basename(path), path: angularIoPath);
+      : new SyncData(title: p.basename(path), path: angularIoPath);
 
   await _generateReadme(path, syncData);
   if (dataExists) await syncDataFile.delete();
 }
 
 /// Generates a README file for the example at [path] based on [syncData].
 Future _generateReadme(String path, SyncData syncData) async {
-  final warningMessage = (syncData.docHref == null)
+  final warningMessage = (syncData.docHref.isEmpty)
       ? '''
 **WARNING:** This example is preliminary and subject to change.
 
@@ -40,21 +41,25 @@ Future _generateReadme(String path, SyncData syncData) async {
             return '- $link';
           }).join('\n');
 
-  final liveExampleSection = syncData.liveExampleHref == null
-      ? 'To run your own copy:\n'
-      : 'You can run a [hosted copy](${syncData.liveExampleHref}) of this'
-      'sample. Or run your own copy:\n';
+  final liveExampleSection = syncData.liveExampleHref.isEmpty
+      ? 'To run your own copy:'
+      : 'You can run a [hosted copy](${syncData.liveExampleHref}) of this '
+      'sample. Or run your own copy:';
+
+  final newIssueUri = '//github.com/angular/angular.io/issues/new'
+      '?labels=dart,example&title=%5BDart%5D%5Bexample%5D%20'
+      '${syncData.id}%3A%20';
 
   final readmeContent = '''
 $warningMessage
 
-${syncData.name}
----------------
+## ${syncData.title}
 
 Welcome to the example application used in angular.io/dart's
-[${syncData.name}](${syncData.docHref ?? syncData.repoHref}) page.
+[${syncData.title}](${syncData.docHref}) page.
 
 $liveExampleSection
+
 1. Clone this repo.
 2. Download the dependencies:
 
@@ -74,41 +79,61 @@ $linkSection
 [the angular.io repository](${syncData.repoHref}) by running the
 [dart-doc-syncer](//github.com/angular/dart-doc-syncer) tool.
 If you find a problem with this sample's code, please open an
-[issue at angular/angular.io](https://github.com/angular/angular.io/issues/new).
+[issue at angular/angular.io]($newIssueUri).
 ''';
 
   final readmeFile = new File(p.join(path, 'README.md'));
   _logger.fine('Generating $readmeFile.');
-  if (dryRun) return new Future.value(null);
   await readmeFile.writeAsStringSync(readmeContent);
 }
 
 /// Holds metadata about the example application that is used to generate a
 /// README file.
 class SyncData {
-  final String name;
+  final String name; // e.g., 'architecture'
+  final String title; // e.g. 'Architecture Overview'
+  final String docPart; // e.g. 'guide' (from 'guide/architecture')
   final String docHref;
   final String repoHref;
   final String liveExampleHref;
   final List<String> links;
 
+  String get id => p.join(docPart, name); // e.g. 'quickstart' or 'guide/architecture'
+
   SyncData(
-      {this.name,
-      this.docHref,
-      this.liveExampleHref,
+      {String name: '',
+      this.title: '',
+      String docPart: '',
+      String docHref: '',
+      String liveExampleHref: '',
       this.links: const [],
-      String repoHref,
+      String repoHref: '',
       String path})
-      : this.repoHref =
-            repoHref ?? '//github.com/angular/angular.io/tree/master/' + path;
+      : this.name = name.isEmpty ? getExampleName(path) : name,
+        this.docPart = docPart,
+        this.docHref = docHref.isEmpty
+            ? p.join(dartDocUriPrefix, docPart, '${getExampleName(path)}.html')
+            : docHref.startsWith('http')
+                ? docHref
+                : p.join(dartDocUriPrefix, docPart, docHref),
+        this.liveExampleHref = liveExampleHref.isEmpty
+            ? p.join(exampleHostUriPrefix, getExampleName(path))
+            : liveExampleHref.startsWith('http')
+                ? liveExampleHref
+                : p.join(exampleHostUriPrefix, liveExampleHref),
+        this.repoHref = repoHref.isEmpty
+            ? '//github.com/angular/angular.io/tree/master/' + path
+            : repoHref;
 
   factory SyncData.fromJson(String json, {String path}) {
     final data = JSON.decode(json);
     return new SyncData(
-        name: data['name'],
-        docHref: data['docHref'],
-        repoHref: data['repoHref'],
-        liveExampleHref: data['liveExampleHref'],
+        name: data['name'] ?? '',
+        title: data['title'] ?? '',
+        docPart: data['docPart'] ?? '',
+        docHref: data['docHref'] ?? '',
+        repoHref: data['repoHref'] ?? '',
+        liveExampleHref: data['liveExampleHref'] ?? '',
         links: data['links'] ?? [],
         path: path);
   }