Migrate to simplified excerpter package (#5696)

To learn about the functionality of the new excerpter tool, visit its
README in
https://github.com/dart-lang/site-shared/blob/main/packages/excerpter/README.md.
Overall it's more strict with a few less features than the original
tool.

It still has some missing features and minor issues, but it's now in a
state where it is sufficient for dart.dev.

Running the script on CI now only takes 3s (down from 21s) when all
excerpts are already up to date! :D

Closes #5593

Author: parlough

.github/workflows/test.yml

@@ -65,7 +65,7 @@ jobs:
       - name: Fetch Dart packages
         run: dart pub get
       - name: Check if excerpts are up to date
-        run: dart run dart_site refresh-excerpts --fail-on-update
+        run: dart run dart_site refresh-excerpts --fail-on-update --dry-run
 
   linkcheck:
     name: Build site and check links

README.md

@@ -226,6 +226,23 @@ on the [Flutter contributors Discord][]!
 
 [Flutter contributors Discord]: https://github.com/flutter/flutter/wiki/Chat
 
+### Refresh code excerpts
+
+A build that fails with the error
+`Error: Some code excerpts needed to be updated!`
+means that one or more code excerpts in the site Markdown files
+aren't identical to the code regions declared
+in the corresponding `.dart` files.
+
+To resolve this error,
+from the root of the `site-www` directory,
+run `./dash_site refresh-excerpts`.
+
+To learn more about creating, editing, and using code excerpts,
+check out the [excerpt updater package documentation][].
+
+[excerpt updater package documentation]: https://github.com/dart-lang/site-shared/tree/main/packages/excerpter#readme
+
 ## [Optional] Deploy to a staging site
 
 Submitted pull requests can be automatically staged

build.excerpt.yaml

@@ -1,14 +1,10 @@
-// #docregion
 void printName(String firstName, String lastName, {String? middleName}) {
   print('$firstName ${middleName ?? ''} $lastName');
 }
-// #enddocregion
 
-void printNameTest() {
-  // #docregion
+void main() {
   printName('Dash', 'Dartisan');
   printName('John', 'Smith', middleName: 'Who');
   // Named arguments can be placed anywhere in the argument list
   printName('John', middleName: 'Who', 'Smith');
-  // #enddocregion
 }

examples/misc/lib/cheatsheet/named_parameters.dart

@@ -4,11 +4,9 @@ int sumUpToFive(int a, [int b = 2, int c = 3, int d = 4, int e = 5]) {
   return a + b + c + d + e;
   // #docregion sum-no-impl
 }
-// #enddocregion sum-no-impl
 
-void mainTest() {
-  // #docregion sum-no-impl
+void main() {
   int newTotal = sumUpToFive(1);
   print(newTotal); // <-- prints 15
-  // #enddocregion sum-no-impl
 }
+// #enddocregion sum-no-impl

examples/misc/lib/cheatsheet/optional_positional_args2.dart

@@ -1,4 +1,4 @@
-import 'package:examples/cheatsheet/named_parameters.dart';
+import 'package:examples/cheatsheet/named_parameters.dart' as named_parameters;
 import 'package:examples/cheatsheet/optional_positional_args.dart'
     as optional_args;
 import 'package:examples/cheatsheet/optional_positional_args2.dart'
@@ -8,7 +8,7 @@ import 'package:test/test.dart';
 void main() {
   test('print_name', () {
     expect(() {
-      printNameTest();
+      named_parameters.main();
     }, prints('Dash  Dartisan\nJohn Who Smith\nJohn Who Smith\n'));
   });
 
@@ -38,7 +38,7 @@ void main() {
 
   test('optional_positional_args_defaulted', () {
     expect(() {
-      defaulted_args.mainTest();
+      defaulted_args.main();
     }, prints('15\n'));
 
     expect(defaulted_args.sumUpToFive(1, 1), equals(14));

examples/misc/test/cheatsheet/arguments_test.dart

@@ -6,11 +6,6 @@ environment:
   sdk: ^3.3.0
 
 dev_dependencies:
-  build_runner: ^2.4.8
-  code_excerpt_updater:
-    path: site-shared/packages/code_excerpt_updater
-  code_excerpter:
-    path: site-shared/packages/code_excerpter
   dart_site:
     path: tool/dart_site
   lints: ^3.0.0

pubspec.yaml

@@ -897,7 +897,7 @@ Positional parameters are the kind you're likely familiar with:
 int sumUp(int a, int b, int c) {
   return a + b + c;
 }
-// ···
+  // ···
   int total = sumUp(1, 2, 3);
 ```
 
@@ -913,7 +913,7 @@ int sumUpToFive(int a, [int? b, int? c, int? d, int? e]) {
   if (e != null) sum += e;
   return sum;
 }
-// ···
+  // ···
   int total = sumUpToFive(1, 2);
   int otherTotal = sumUpToFive(1, 2, 3, 4, 5);
 ```
@@ -927,9 +927,11 @@ Their default value is null unless you provide another default value:
 int sumUpToFive(int a, [int b = 2, int c = 3, int d = 4, int e = 5]) {
   // ···
 }
-// ···
+
+void main() {
   int newTotal = sumUpToFive(1);
   print(newTotal); // <-- prints 15
+}
 ```
 
 ### Code example {:.no_toc}
@@ -1040,11 +1042,13 @@ unless they're explicitly marked as `required`.
 void printName(String firstName, String lastName, {String? middleName}) {
   print('$firstName ${middleName ?? ''} $lastName');
 }
-// ···
+
+void main() {
   printName('Dash', 'Dartisan');
   printName('John', 'Smith', middleName: 'Who');
   // Named arguments can be placed anywhere in the argument list
   printName('John', middleName: 'Who', 'Smith');
+}
 ```
 
 As you might expect,

site-shared

@@ -463,23 +463,23 @@ Future<void> parseJson(String message) async {
   import 'dart:async';
   import 'dart:convert';
   import 'dart:isolate';
-
+  
   void main() async {
     final worker = Worker();
     await worker.spawn();
     await worker.parseJson('{"key":"value"}');
   }
-
+  
   class Worker {
     late SendPort _sendPort;
     final Completer<void> _isolateReady = Completer.sync();
-
+  
     Future<void> spawn() async {
       final receivePort = ReceivePort();
       receivePort.listen(_handleResponsesFromIsolate);
       await Isolate.spawn(_startRemoteIsolate, receivePort.sendPort);
     }
-
+  
     void _handleResponsesFromIsolate(dynamic message) {
       if (message is SendPort) {
         _sendPort = message;
@@ -488,19 +488,19 @@ Future<void> parseJson(String message) async {
         print(message);
       }
     }
-
+  
     static void _startRemoteIsolate(SendPort port) {
       final receivePort = ReceivePort();
       port.send(receivePort.sendPort);
-
+  
       receivePort.listen((dynamic message) async {
         if (message is String) {
           final transformed = jsonDecode(message);
           port.send(transformed);
         }
       });
     }
-
+  
     Future<void> parseJson(String message) async {
       await _isolateReady.future;
       _sendPort.send(message);

src/content/codelabs/dart-cheatsheet.md

@@ -66,7 +66,7 @@ that the mixin doesn't define.
 As the following example shows, you can restrict a mixin's use
 by using the `on` keyword to specify the required superclass:
 
-<?code-excerpt "misc/lib/language_tour/classes/orchestra.dart (mixin-on)" plaster="none" replace="/on Musician2/[!on Musician!]/g" ?>
+<?code-excerpt "misc/lib/language_tour/classes/orchestra.dart (mixin-on)" plaster="none" replace="/on Musician2/[!on Musician!]/g"?>
 ```dart
 class Musician {
   // ...

src/content/language/isolates.md

@@ -22,7 +22,7 @@ final class CheckAllCommand extends Command<int> {
       ['format-dart', '--check'],
       ['analyze-dart'],
       ['test-dart'],
-      ['refresh-excerpts', '--fail-on-update'],
+      ['refresh-excerpts', '--fail-on-update', '--dry-run'],
       ['verify-firebase-json'],
     ];