Skip to content

Commit 30bc997

Browse files
authored
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
1 parent 5ffed01 commit 30bc997

File tree

14 files changed

+112
-179
lines changed

14 files changed

+112
-179
lines changed

.github/workflows/test.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ jobs:
6565
- name: Fetch Dart packages
6666
run: dart pub get
6767
- name: Check if excerpts are up to date
68-
run: dart run dart_site refresh-excerpts --fail-on-update
68+
run: dart run dart_site refresh-excerpts --fail-on-update --dry-run
6969

7070
linkcheck:
7171
name: Build site and check links

README.md

+17
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,23 @@ on the [Flutter contributors Discord][]!
226226

227227
[Flutter contributors Discord]: https://github.com/flutter/flutter/wiki/Chat
228228

229+
### Refresh code excerpts
230+
231+
A build that fails with the error
232+
`Error: Some code excerpts needed to be updated!`
233+
means that one or more code excerpts in the site Markdown files
234+
aren't identical to the code regions declared
235+
in the corresponding `.dart` files.
236+
237+
To resolve this error,
238+
from the root of the `site-www` directory,
239+
run `./dash_site refresh-excerpts`.
240+
241+
To learn more about creating, editing, and using code excerpts,
242+
check out the [excerpt updater package documentation][].
243+
244+
[excerpt updater package documentation]: https://github.com/dart-lang/site-shared/tree/main/packages/excerpter#readme
245+
229246
## [Optional] Deploy to a staging site
230247

231248
Submitted pull requests can be automatically staged

build.excerpt.yaml

-15
This file was deleted.
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
1-
// #docregion
21
void printName(String firstName, String lastName, {String? middleName}) {
32
print('$firstName ${middleName ?? ''} $lastName');
43
}
5-
// #enddocregion
64

7-
void printNameTest() {
8-
// #docregion
5+
void main() {
96
printName('Dash', 'Dartisan');
107
printName('John', 'Smith', middleName: 'Who');
118
// Named arguments can be placed anywhere in the argument list
129
printName('John', middleName: 'Who', 'Smith');
13-
// #enddocregion
1410
}

examples/misc/lib/cheatsheet/optional_positional_args2.dart

+2-4
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,9 @@ int sumUpToFive(int a, [int b = 2, int c = 3, int d = 4, int e = 5]) {
44
return a + b + c + d + e;
55
// #docregion sum-no-impl
66
}
7-
// #enddocregion sum-no-impl
87

9-
void mainTest() {
10-
// #docregion sum-no-impl
8+
void main() {
119
int newTotal = sumUpToFive(1);
1210
print(newTotal); // <-- prints 15
13-
// #enddocregion sum-no-impl
1411
}
12+
// #enddocregion sum-no-impl

examples/misc/test/cheatsheet/arguments_test.dart

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import 'package:examples/cheatsheet/named_parameters.dart';
1+
import 'package:examples/cheatsheet/named_parameters.dart' as named_parameters;
22
import 'package:examples/cheatsheet/optional_positional_args.dart'
33
as optional_args;
44
import 'package:examples/cheatsheet/optional_positional_args2.dart'
@@ -8,7 +8,7 @@ import 'package:test/test.dart';
88
void main() {
99
test('print_name', () {
1010
expect(() {
11-
printNameTest();
11+
named_parameters.main();
1212
}, prints('Dash Dartisan\nJohn Who Smith\nJohn Who Smith\n'));
1313
});
1414

@@ -38,7 +38,7 @@ void main() {
3838

3939
test('optional_positional_args_defaulted', () {
4040
expect(() {
41-
defaulted_args.mainTest();
41+
defaulted_args.main();
4242
}, prints('15\n'));
4343

4444
expect(defaulted_args.sumUpToFive(1, 1), equals(14));

pubspec.yaml

-5
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,6 @@ environment:
66
sdk: ^3.3.0
77

88
dev_dependencies:
9-
build_runner: ^2.4.8
10-
code_excerpt_updater:
11-
path: site-shared/packages/code_excerpt_updater
12-
code_excerpter:
13-
path: site-shared/packages/code_excerpter
149
dart_site:
1510
path: tool/dart_site
1611
lints: ^3.0.0

site-shared

Submodule site-shared updated 66 files

src/content/codelabs/dart-cheatsheet.md

+8-4
Original file line numberDiff line numberDiff line change
@@ -897,7 +897,7 @@ Positional parameters are the kind you're likely familiar with:
897897
int sumUp(int a, int b, int c) {
898898
return a + b + c;
899899
}
900-
// ···
900+
// ···
901901
int total = sumUp(1, 2, 3);
902902
```
903903

@@ -913,7 +913,7 @@ int sumUpToFive(int a, [int? b, int? c, int? d, int? e]) {
913913
if (e != null) sum += e;
914914
return sum;
915915
}
916-
// ···
916+
// ···
917917
int total = sumUpToFive(1, 2);
918918
int otherTotal = sumUpToFive(1, 2, 3, 4, 5);
919919
```
@@ -927,9 +927,11 @@ Their default value is null unless you provide another default value:
927927
int sumUpToFive(int a, [int b = 2, int c = 3, int d = 4, int e = 5]) {
928928
// ···
929929
}
930-
// ···
930+
931+
void main() {
931932
int newTotal = sumUpToFive(1);
932933
print(newTotal); // <-- prints 15
934+
}
933935
```
934936

935937
### Code example {:.no_toc}
@@ -1040,11 +1042,13 @@ unless they're explicitly marked as `required`.
10401042
void printName(String firstName, String lastName, {String? middleName}) {
10411043
print('$firstName ${middleName ?? ''} $lastName');
10421044
}
1043-
// ···
1045+
1046+
void main() {
10441047
printName('Dash', 'Dartisan');
10451048
printName('John', 'Smith', middleName: 'Who');
10461049
// Named arguments can be placed anywhere in the argument list
10471050
printName('John', middleName: 'Who', 'Smith');
1051+
}
10481052
```
10491053

10501054
As you might expect,

src/content/language/isolates.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -463,23 +463,23 @@ Future<void> parseJson(String message) async {
463463
import 'dart:async';
464464
import 'dart:convert';
465465
import 'dart:isolate';
466-
466+
467467
void main() async {
468468
final worker = Worker();
469469
await worker.spawn();
470470
await worker.parseJson('{"key":"value"}');
471471
}
472-
472+
473473
class Worker {
474474
late SendPort _sendPort;
475475
final Completer<void> _isolateReady = Completer.sync();
476-
476+
477477
Future<void> spawn() async {
478478
final receivePort = ReceivePort();
479479
receivePort.listen(_handleResponsesFromIsolate);
480480
await Isolate.spawn(_startRemoteIsolate, receivePort.sendPort);
481481
}
482-
482+
483483
void _handleResponsesFromIsolate(dynamic message) {
484484
if (message is SendPort) {
485485
_sendPort = message;
@@ -488,19 +488,19 @@ Future<void> parseJson(String message) async {
488488
print(message);
489489
}
490490
}
491-
491+
492492
static void _startRemoteIsolate(SendPort port) {
493493
final receivePort = ReceivePort();
494494
port.send(receivePort.sendPort);
495-
495+
496496
receivePort.listen((dynamic message) async {
497497
if (message is String) {
498498
final transformed = jsonDecode(message);
499499
port.send(transformed);
500500
}
501501
});
502502
}
503-
503+
504504
Future<void> parseJson(String message) async {
505505
await _isolateReady.future;
506506
_sendPort.send(message);

src/content/language/mixins.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ that the mixin doesn't define.
6666
As the following example shows, you can restrict a mixin's use
6767
by using the `on` keyword to specify the required superclass:
6868

69-
<?code-excerpt "misc/lib/language_tour/classes/orchestra.dart (mixin-on)" plaster="none" replace="/on Musician2/[!on Musician!]/g" ?>
69+
<?code-excerpt "misc/lib/language_tour/classes/orchestra.dart (mixin-on)" plaster="none" replace="/on Musician2/[!on Musician!]/g"?>
7070
```dart
7171
class Musician {
7272
// ...

tool/dart_site/lib/src/commands/check_all.dart

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ final class CheckAllCommand extends Command<int> {
2222
['format-dart', '--check'],
2323
['analyze-dart'],
2424
['test-dart'],
25-
['refresh-excerpts', '--fail-on-update'],
25+
['refresh-excerpts', '--fail-on-update', '--dry-run'],
2626
['verify-firebase-json'],
2727
];
2828

0 commit comments

Comments
 (0)