[flutter_plugin_tools] Reimplements the excerpt system inline in the tool, rather than relying on a separate package. (#4417)

* Allows excerpts to come from any package, not just examples.
* Fixes a bug in the excerpting logic that was causing a stray `}` to appear in one example.
* Removes the need for `build.excerpt.yaml` files.
* Remove the dependency on build_runner for excerpts.
* Reduces the time to generate the excerpts from about 10 minutes to about 5 seconds.
* Almost certainly fixes flutter/flutter#107180 (untested).

The new logic is not quite backwards compatible; the `path-base` feature now specifies a real path to the actual source directories, rather than a path into the invisible generated `excerpts/` directory with its special structure. Also, a number of features from the previous package that were not actually used in this repository are no longer supported (such as having multiple section names per `#docregion` pragma).

Author: Hixie

.gitmodules

@@ -1,6 +1,6 @@
 # Camera Plugin
 
-<?code-excerpt path-base="excerpts/packages/camera_example"?>
+<?code-excerpt path-base="example/lib"?>
 
 [![pub package](https://img.shields.io/pub/v/camera.svg)](https://pub.dev/packages/camera)
 

packages/camera/camera/README.md

@@ -1,6 +1,6 @@
 # file_selector
 
-<?code-excerpt path-base="excerpts/packages/file_selector_example"?>
+<?code-excerpt path-base="example/lib"?>
 
 [![pub package](https://img.shields.io/pub/v/file_selector.svg)](https://pub.dartlang.org/packages/file_selector)
 
@@ -36,7 +36,7 @@ Please also take a look at our [example][example] app.
 #### Open a single file
 
 <?code-excerpt "open_image_page.dart (SingleOpen)"?>
-``` dart
+```dart
 const XTypeGroup typeGroup = XTypeGroup(
   label: 'images',
   extensions: <String>['jpg', 'png'],
@@ -48,7 +48,7 @@ final XFile? file =
 #### Open multiple files at once
 
 <?code-excerpt "open_multiple_images_page.dart (MultiOpen)"?>
-``` dart
+```dart
 const XTypeGroup jpgsTypeGroup = XTypeGroup(
   label: 'JPEGs',
   extensions: <String>['jpg', 'jpeg'],

packages/camera/camera/example/build.excerpt.yaml

@@ -1,4 +1,4 @@
-<?code-excerpt path-base="excerpts/packages/flutter_adaptive_scaffold_example"?>
+<?code-excerpt path-base="example/lib"?>
 
 # Adaptive Scaffold
 
@@ -35,75 +35,74 @@ animation should use AdaptiveLayout.
 
 <?code-excerpt "adaptive_scaffold_demo.dart (Example)"?>
 ```dart
-  @override
-  Widget build(BuildContext context) {
-    // Define the children to display within the body at different breakpoints.
-    final List<Widget> children = <Widget>[
-      for (int i = 0; i < 10; i++)
-        Padding(
-          padding: const EdgeInsets.all(8.0),
-          child: Container(
-            color: const Color.fromARGB(255, 255, 201, 197),
-            height: 400,
-          ),
-        )
-    ];
-
-    return AdaptiveScaffold(
-      // An option to override the default breakpoints used for small, medium,
-      // and large.
-      smallBreakpoint: const WidthPlatformBreakpoint(end: 700),
-      mediumBreakpoint: const WidthPlatformBreakpoint(begin: 700, end: 1000),
-      largeBreakpoint: const WidthPlatformBreakpoint(begin: 1000),
-      useDrawer: false,
-      selectedIndex: _selectedTab,
-      onSelectedIndexChange: (int index) {
-        setState(() {
-          _selectedTab = index;
-        });
-      },
-      destinations: const <NavigationDestination>[
-        NavigationDestination(
-          icon: Icon(Icons.inbox_outlined),
-          selectedIcon: Icon(Icons.inbox),
-          label: 'Inbox',
-        ),
-        NavigationDestination(
-          icon: Icon(Icons.article_outlined),
-          selectedIcon: Icon(Icons.article),
-          label: 'Articles',
-        ),
-        NavigationDestination(
-          icon: Icon(Icons.chat_outlined),
-          selectedIcon: Icon(Icons.chat),
-          label: 'Chat',
-        ),
-        NavigationDestination(
-          icon: Icon(Icons.video_call_outlined),
-          selectedIcon: Icon(Icons.video_call),
-          label: 'Video',
-        ),
-        NavigationDestination(
-          icon: Icon(Icons.home_outlined),
-          selectedIcon: Icon(Icons.home),
-          label: 'Inbox',
+@override
+Widget build(BuildContext context) {
+  // Define the children to display within the body at different breakpoints.
+  final List<Widget> children = <Widget>[
+    for (int i = 0; i < 10; i++)
+      Padding(
+        padding: const EdgeInsets.all(8.0),
+        child: Container(
+          color: const Color.fromARGB(255, 255, 201, 197),
+          height: 400,
         ),
-      ],
-      body: (_) => GridView.count(crossAxisCount: 2, children: children),
-      smallBody: (_) => ListView.builder(
-        itemCount: children.length,
-        itemBuilder: (_, int idx) => children[idx],
+      )
+  ];
+
+  return AdaptiveScaffold(
+    // An option to override the default breakpoints used for small, medium,
+    // and large.
+    smallBreakpoint: const WidthPlatformBreakpoint(end: 700),
+    mediumBreakpoint: const WidthPlatformBreakpoint(begin: 700, end: 1000),
+    largeBreakpoint: const WidthPlatformBreakpoint(begin: 1000),
+    useDrawer: false,
+    selectedIndex: _selectedTab,
+    onSelectedIndexChange: (int index) {
+      setState(() {
+        _selectedTab = index;
+      });
+    },
+    destinations: const <NavigationDestination>[
+      NavigationDestination(
+        icon: Icon(Icons.inbox_outlined),
+        selectedIcon: Icon(Icons.inbox),
+        label: 'Inbox',
+      ),
+      NavigationDestination(
+        icon: Icon(Icons.article_outlined),
+        selectedIcon: Icon(Icons.article),
+        label: 'Articles',
+      ),
+      NavigationDestination(
+        icon: Icon(Icons.chat_outlined),
+        selectedIcon: Icon(Icons.chat),
+        label: 'Chat',
+      ),
+      NavigationDestination(
+        icon: Icon(Icons.video_call_outlined),
+        selectedIcon: Icon(Icons.video_call),
+        label: 'Video',
       ),
-      // Define a default secondaryBody.
-      secondaryBody: (_) => Container(
-        color: const Color.fromARGB(255, 234, 158, 192),
+      NavigationDestination(
+        icon: Icon(Icons.home_outlined),
+        selectedIcon: Icon(Icons.home),
+        label: 'Inbox',
       ),
-      // Override the default secondaryBody during the smallBreakpoint to be
-      // empty. Must use AdaptiveScaffold.emptyBuilder to ensure it is properly
-      // overridden.
-      smallSecondaryBody: AdaptiveScaffold.emptyBuilder,
-    );
-  }
+    ],
+    body: (_) => GridView.count(crossAxisCount: 2, children: children),
+    smallBody: (_) => ListView.builder(
+      itemCount: children.length,
+      itemBuilder: (_, int idx) => children[idx],
+    ),
+    // Define a default secondaryBody.
+    secondaryBody: (_) => Container(
+      color: const Color.fromARGB(255, 234, 158, 192),
+    ),
+    // Override the default secondaryBody during the smallBreakpoint to be
+    // empty. Must use AdaptiveScaffold.emptyBuilder to ensure it is properly
+    // overridden.
+    smallSecondaryBody: AdaptiveScaffold.emptyBuilder,
+  );
 }
 ```
 

packages/file_selector/file_selector/README.md

@@ -124,5 +124,5 @@ class _MyHomePageState extends State<MyHomePage> {
       smallSecondaryBody: AdaptiveScaffold.emptyBuilder,
     );
   }
-// #enddocregion
+// #enddocregion Example
 }

packages/file_selector/file_selector/example/build.excerpt.yaml

@@ -17,16 +17,16 @@ const String _data = '''
 ''';
 
 const String _notes = '''
-# Shrink wrap demo 
+# Shrink wrap demo
 ---
 
 ## Overview
 
 This example demonstrates how `MarkdownBody`'s `shrinkWrap` property works.
 
-- If `shrinkWrap` is `true`, `MarkdownBody` will take the minimum height that 
+- If `shrinkWrap` is `true`, `MarkdownBody` will take the minimum height that
   wraps its content.
-- If `shrinkWrap` is `false`, `MarkdownBody` will expand to the maximum allowed 
+- If `shrinkWrap` is `false`, `MarkdownBody` will expand to the maximum allowed
   height.
 ''';
 

packages/flutter_adaptive_scaffold/README.md

@@ -1,5 +1,3 @@
-<?code-excerpt path-base="excerpts/packages/google_identity_services_web_example"?>
-
 # google_identity_services_web
 
 A JS-interop layer for Google Identity's Sign In With Google SDK.
@@ -29,7 +27,7 @@ script tag [as recommended](https://developers.google.com/identity/gsi/web/guide
 Place the `script` tag in the `<head>` of your site, next to the script tag that
 loads `flutter.js`, so the browser can downloaded both in parallel:
 
-<?code-excerpt "../../web/index-with-script-tag.html (script-tag)"?>
+<?code-excerpt "example/web/index-with-script-tag.html (script-tag)"?>
 ```html
 <head>
 <!-- ··· -->
@@ -46,7 +44,7 @@ An alternative way, that downloads the SDK on demand, is to use the
 **`loadWebSdk`** function provided by the library. A simple location to embed
 this in a Flutter Web only app can be the `main.dart`:
 
-<?code-excerpt "main.dart (use-loader)"?>
+<?code-excerpt "example/lib/main.dart (use-loader)"?>
 ```dart
 import 'package:google_identity_services_web/loader.dart' as gis;
 // ···