Update readme to document build and serve feature

webdev/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 0.1.4
 
 - Require and use features from `build_runner` 0.8.2.
+- Added a `--[no]-release`.
 
 ## 0.1.3+1
 

webdev/README.md

@@ -15,19 +15,40 @@ $ pub global activate webdev
 
 ## Usage
 
+`webdev` provides two commands: `serve` and `build`.
+
+### `webdev serve`
+
 ```console
-$ webdev
-A tool to develop Dart web projects.
+$ webdev help serve
+Run a local web development server and a file system watcher that re-builds on changes.
+
+Usage: webdev serve [arguments] [<directory>[:<port>]]...
+-h, --help            Print this usage information.
+-r, --[no-]release    Build with release mode defaults for builders.
+-o, --output          A directory to write the result of a build to. Or a mapping from a top-level directory in the package to the directory to write a filtered build output to. For example "web:deploy".
+-v, --verbose         Enables verbose logging.
+    --hostname        Specify the hostname to serve on
+                      (defaults to "localhost")
+
+    --log-requests    Enables logging for each request to the server.
 
-Usage: webdev <command> [arguments]
+Run "webdev help" to see global options.
+```
+
+### `webdev build`
+
+```console
+$ webdev help build
+Run builders to build a package.
 
-Global options:
--h, --help    Print this usage information.
+Usage: webdev build [arguments]
+-h, --help            Print this usage information.
+-r, --[no-]release    Build with release mode defaults for builders.
+                      (defaults to on)
 
-Available commands:
-  build   Run builders to build a package.
-  help    Display help information for webdev.
-  serve   Run a local web development server and a file system watcher that re-builds on changes.
+-o, --output          A directory to write the result of a build to. Or a mapping from a top-level directory in the package to the directory to write a filtered build output to. For example "web:deploy".
+-v, --verbose         Enables verbose logging.
 
-Run "webdev help <command>" for more information about a command.
+Run "webdev help" to see global options.
 ```

webdev/test/integration_test.dart

@@ -11,28 +11,11 @@ import 'package:test_descriptor/test_descriptor.dart' as d;
 import 'package:test_process/test_process.dart';
 import 'package:webdev/src/util.dart';
 
-final _webdevBin = p.absolute(p.join('bin', 'webdev.dart'));
-
-Future<TestProcess> _runWebDev(List<String> args, {String workingDirectory}) {
-  var fullArgs = [_webdevBin]..addAll(args);
-
-  return TestProcess.start(dartPath, fullArgs,
-      workingDirectory: workingDirectory);
-}
+import 'test_utils.dart';
 
 void main() {
-  test('README contains help output', () async {
-    var process = await _runWebDev([]);
-    var output = (await process.stdoutStream().join('\n')).trim();
-    await process.shouldExit(0);
-
-    var readme = new File('README.md');
-    expect(readme.readAsStringSync(),
-        contains('```console\n\$ webdev\n$output\n```'));
-  });
-
   test('non-existant commands create errors', () async {
-    var process = await _runWebDev(['monkey']);
+    var process = await runWebDev(['monkey']);
 
     await expectLater(
         process.stdout, emits('Could not find a command named "monkey".'));
@@ -43,7 +26,7 @@ void main() {
   test('should fail in a package without a build_runner dependency', () async {
     // Running on the `webdev` package directory – which has no dependency on
     // build runner.
-    var process = await _runWebDev(['build']);
+    var process = await runWebDev(['build']);
     var output = (await process.stdoutStream().join('\n')).trim();
 
     expect(output, contains(r'''webdev could not run for this project.
@@ -63,7 +46,7 @@ name: sample
         await d.file('.packages', '''
 ''').create();
 
-        var process = await _runWebDev(['build'], workingDirectory: d.sandbox);
+        var process = await runWebDev(['build'], workingDirectory: d.sandbox);
 
         await expectLater(
             process.stdout, emits('webdev could not run for this project.'));
@@ -77,7 +60,7 @@ name: sample
   });
 
   test('no pubspec.yaml', () async {
-    var process = await _runWebDev(['build'], workingDirectory: d.sandbox);
+    var process = await runWebDev(['build'], workingDirectory: d.sandbox);
 
     var output = await process.stdoutStream().join('\n');
 
@@ -91,7 +74,7 @@ name: sample
 name: sample
 ''').create();
 
-    var process = await _runWebDev(['build'], workingDirectory: d.sandbox);
+    var process = await runWebDev(['build'], workingDirectory: d.sandbox);
 
     var output = await process.stdoutStream().join('\n');
 
@@ -108,7 +91,7 @@ name: sample
 
     await d.file('pubspec.lock', _pubspecLock()).create();
 
-    var process = await _runWebDev(['build'], workingDirectory: d.sandbox);
+    var process = await runWebDev(['build'], workingDirectory: d.sandbox);
 
     var output = await process.stdoutStream().join('\n');
 
@@ -127,7 +110,7 @@ name: sample
 
     await d.file('.packages', '').create();
 
-    var process = await _runWebDev(['build'], workingDirectory: d.sandbox);
+    var process = await runWebDev(['build'], workingDirectory: d.sandbox);
 
     var output = await process.stdoutStream().join('\n');
 
@@ -152,7 +135,7 @@ dependencies:
   args: ^1.0.0
 ''').create();
 
-    var process = await _runWebDev(['build'], workingDirectory: d.sandbox);
+    var process = await runWebDev(['build'], workingDirectory: d.sandbox);
 
     var output = await process.stdoutStream().join('\n');
 
@@ -183,7 +166,7 @@ dependencies:
           args.add('--no-release');
         }
 
-        process = await _runWebDev(args, workingDirectory: exampleDirectory);
+        process = await runWebDev(args, workingDirectory: exampleDirectory);
 
         var output = await process.stdoutStream().join('\n');
 

webdev/test/readme_test.dart

@@ -0,0 +1,29 @@
+// Copyright (c) 2018, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+import 'dart:io';
+
+import 'package:test/test.dart';
+
+import 'test_utils.dart';
+
+void main() {
+  test('help build', () => _readmeCheck(['help', 'build']));
+  test('help serve', () => _readmeCheck(['help', 'serve']));
+}
+
+Future _readmeCheck(List<String> args) async {
+  var process = await runWebDev(args);
+  var output = (await process.stdoutStream().join('\n')).trim();
+  await process.shouldExit(0);
+
+  var readme = new File('README.md');
+
+  var command = (['webdev']..addAll(args)).join(' ');
+  var expected = '```console\n\$ $command\n$output\n```';
+
+  printOnFailure(expected);
+  expect(readme.readAsStringSync(), contains(expected));
+}

webdev/test/test_utils.dart

@@ -0,0 +1,18 @@
+// Copyright (c) 2018, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+
+import 'package:path/path.dart' as p;
+import 'package:test_process/test_process.dart';
+import 'package:webdev/src/util.dart';
+
+final _webdevBin = p.absolute(p.join('bin', 'webdev.dart'));
+
+Future<TestProcess> runWebDev(List<String> args, {String workingDirectory}) {
+  var fullArgs = [_webdevBin]..addAll(args);
+
+  return TestProcess.start(dartPath, fullArgs,
+      workingDirectory: workingDirectory);
+}