[flutter_plugin_tools] Adds update-excerpts command (#5339)

Author: stuartmorgan-g

.cirrus.yml

@@ -155,6 +155,10 @@ task:
       analyze_script:
         - ./script/tool_runner.sh analyze --skip-if-not-supporting-flutter-version="$CHANNEL" --custom-analysis=script/configs/custom_analysis.yaml
         - echo "If this test fails, the minumum Flutter version should be updated"
+    - name: readme_excerpts
+      env:
+        CIRRUS_CLONE_SUBMODULES: true
+      script: ./script/tool_runner.sh update-excerpts --fail-on-change
     ### Web tasks ###
     - name: web-build_all_plugins
       env:

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "site-shared"]
+	path = site-shared
+	url = https://github.com/dart-lang/site-shared

packages/camera/camera/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.9.4+21
+
+* Fixes README code samples.
+
 ## 0.9.4+20
 
 * Fixes an issue with the orientation of videos recorded in landscape on Android.

packages/camera/camera/README.md

@@ -1,5 +1,7 @@
 # Camera Plugin
 
+<?code-excerpt path-base="excerpts/packages/camera_example"?>
+
 [![pub package](https://img.shields.io/pub/v/camera.svg)](https://pub.dev/packages/camera)
 
 A Flutter plugin for iOS, Android and Web allowing access to the device cameras.
@@ -59,33 +61,35 @@ For web integration details, see the
 
 As of version [0.5.0](https://github.com/flutter/plugins/blob/master/packages/camera/CHANGELOG.md#050) of the camera plugin, lifecycle changes are no longer handled by the plugin. This means developers are now responsible to control camera resources when the lifecycle state is updated. Failure to do so might lead to unexpected behavior (for example as described in issue [#39109](https://github.com/flutter/flutter/issues/39109)). Handling lifecycle changes can be done by overriding the `didChangeAppLifecycleState` method like so:
 
+<?code-excerpt "main.dart (AppLifecycle)"?>
 ```dart
-  @override
-  void didChangeAppLifecycleState(AppLifecycleState state) {
-    // App state changed before we got the chance to initialize.
-    if (controller == null || !controller.value.isInitialized) {
-      return;
-    }
-    if (state == AppLifecycleState.inactive) {
-      controller?.dispose();
-    } else if (state == AppLifecycleState.resumed) {
-      if (controller != null) {
-        onNewCameraSelected(controller.description);
-      }
-    }
+@override
+void didChangeAppLifecycleState(AppLifecycleState state) {
+  final CameraController? cameraController = controller;
+
+  // App state changed before we got the chance to initialize.
+  if (cameraController == null || !cameraController.value.isInitialized) {
+    return;
   }
+
+  if (state == AppLifecycleState.inactive) {
+    cameraController.dispose();
+  } else if (state == AppLifecycleState.resumed) {
+    onNewCameraSelected(cameraController.description);
+  }
+}
 ```
 
 ### Example
 
 Here is a small example flutter app displaying a full screen camera preview.
 
+<?code-excerpt "readme_full_example.dart (FullAppExample)"?>
 ```dart
-import 'dart:async';
-import 'package:flutter/material.dart';
 import 'package:camera/camera.dart';
+import 'package:flutter/material.dart';
 
-List<CameraDescription> cameras;
+late List<CameraDescription> cameras;
 
 Future<void> main() async {
   WidgetsFlutterBinding.ensureInitialized();
@@ -100,7 +104,7 @@ class CameraApp extends StatefulWidget {
 }
 
 class _CameraAppState extends State<CameraApp> {
-  CameraController controller;
+  late CameraController controller;
 
   @override
   void initState() {
@@ -116,7 +120,7 @@ class _CameraAppState extends State<CameraApp> {
 
   @override
   void dispose() {
-    controller?.dispose();
+    controller.dispose();
     super.dispose();
   }
 
@@ -130,7 +134,6 @@ class _CameraAppState extends State<CameraApp> {
     );
   }
 }
-
 ```
 
 For a more elaborate usage example see [here](https://github.com/flutter/plugins/tree/main/packages/camera/camera/example).

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

@@ -0,0 +1,15 @@
+targets:
+  $default:
+    sources:
+      include:
+        - lib/**
+        # Some default includes that aren't really used here but will prevent
+        # false-negative warnings:
+        - $package$
+        - lib/$lib$
+      exclude:
+        - '**/.*/**'
+        - '**/build/**'
+    builders:
+      code_excerpter|code_excerpter:
+        enabled: true

packages/camera/camera/example/lib/main.dart

@@ -106,6 +106,7 @@ class _CameraExampleHomeState extends State<CameraExampleHome>
     super.dispose();
   }
 
+  // #docregion AppLifecycle
   @override
   void didChangeAppLifecycleState(AppLifecycleState state) {
     final CameraController? cameraController = controller;
@@ -121,6 +122,7 @@ class _CameraExampleHomeState extends State<CameraExampleHome>
       onNewCameraSelected(cameraController.description);
     }
   }
+  // #enddocregion AppLifecycle
 
   @override
   Widget build(BuildContext context) {

packages/camera/camera/example/lib/readme_full_example.dart

@@ -0,0 +1,56 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// ignore_for_file: public_member_api_docs
+
+// #docregion FullAppExample
+import 'package:camera/camera.dart';
+import 'package:flutter/material.dart';
+
+late List<CameraDescription> cameras;
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  cameras = await availableCameras();
+  runApp(CameraApp());
+}
+
+class CameraApp extends StatefulWidget {
+  @override
+  _CameraAppState createState() => _CameraAppState();
+}
+
+class _CameraAppState extends State<CameraApp> {
+  late CameraController controller;
+
+  @override
+  void initState() {
+    super.initState();
+    controller = CameraController(cameras[0], ResolutionPreset.max);
+    controller.initialize().then((_) {
+      if (!mounted) {
+        return;
+      }
+      setState(() {});
+    });
+  }
+
+  @override
+  void dispose() {
+    controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (!controller.value.isInitialized) {
+      return Container();
+    }
+    return MaterialApp(
+      home: CameraPreview(controller),
+    );
+  }
+}
+// #enddocregion FullAppExample

packages/camera/camera/example/pubspec.yaml

@@ -20,6 +20,7 @@ dependencies:
   video_player: ^2.1.4
 
 dev_dependencies:
+  build_runner: ^2.1.10
   flutter_driver:
     sdk: flutter
   flutter_test:

packages/camera/camera/pubspec.yaml

@@ -4,7 +4,7 @@ description: A Flutter plugin for controlling the camera. Supports previewing
   Dart.
 repository: https://github.com/flutter/plugins/tree/main/packages/camera/camera
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22
-version: 0.9.4+20
+version: 0.9.4+21
 
 environment:
   sdk: ">=2.14.0 <3.0.0"

script/tool/CHANGELOG.md

@@ -1,5 +1,8 @@
-## NEXT
+## 0.8.3
 
+- Adds a new `update-excerpts` command to maintain README files using the
+  `code-excerpter` package from flutter/site-shared.
+- `license-check` now ignores submodules.
 - Allows `make-deps-path-based` to skip packages it has alredy rewritten, so
   that running multiple times won't fail after the first time.
 

script/tool/README.md

@@ -107,6 +107,17 @@ dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --ios --android
 dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --macos --packages plugin_name
 ```
 
+### Update README.md from Example Sources
+
+`update-excerpts` requires sources that are in a submodule. If you didn't clone
+with submodules, you will need to `git submodule update --init --recursive`
+before running this command.
+
+```sh
+cd <repository root>
+dart run ./script/tool/bin/flutter_plugin_tools.dart update-excerpts --packages plugin_name
+```
+
 ### Publish a Release
 
 **Releases are automated for `flutter/plugins` and `flutter/packages`.**

script/tool/lib/src/license_check_command.dart

@@ -3,7 +3,9 @@
 // found in the LICENSE file.
 
 import 'package:file/file.dart';
+import 'package:git/git.dart';
 import 'package:path/path.dart' as p;
+import 'package:platform/platform.dart';
 
 import 'common/core.dart';
 import 'common/plugin_command.dart';
@@ -105,7 +107,9 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 /// Validates that code files have copyright and license blocks.
 class LicenseCheckCommand extends PluginCommand {
   /// Creates a new license check command for [packagesDir].
-  LicenseCheckCommand(Directory packagesDir) : super(packagesDir);
+  LicenseCheckCommand(Directory packagesDir,
+      {Platform platform = const LocalPlatform(), GitDir? gitDir})
+      : super(packagesDir, platform: platform, gitDir: gitDir);
 
   @override
   final String name = 'license-check';
@@ -116,7 +120,14 @@ class LicenseCheckCommand extends PluginCommand {
 
   @override
   Future<void> run() async {
-    final Iterable<File> allFiles = await _getAllFiles();
+    // Create a set of absolute paths to submodule directories, with trailing
+    // separator, to do prefix matching with to test directory inclusion.
+    final Iterable<String> submodulePaths = (await _getSubmoduleDirectories())
+        .map(
+            (Directory dir) => '${dir.absolute.path}${platform.pathSeparator}');
+
+    final Iterable<File> allFiles = (await _getAllFiles()).where(
+        (File file) => !submodulePaths.any(file.absolute.path.startsWith));
 
     final Iterable<File> codeFiles = allFiles.where((File file) =>
         _codeFileExtensions.contains(p.extension(file.path)) &&
@@ -275,6 +286,24 @@ class LicenseCheckCommand extends PluginCommand {
       .where((FileSystemEntity entity) => entity is File)
       .map((FileSystemEntity file) => file as File)
       .toList();
+
+  // Returns the directories containing mapped submodules, if any.
+  Future<Iterable<Directory>> _getSubmoduleDirectories() async {
+    final List<Directory> submodulePaths = <Directory>[];
+    final Directory repoRoot =
+        packagesDir.fileSystem.directory((await gitDir).path);
+    final File submoduleSpec = repoRoot.childFile('.gitmodules');
+    if (submoduleSpec.existsSync()) {
+      final RegExp pathLine = RegExp(r'path\s*=\s*(.*)');
+      for (final String line in submoduleSpec.readAsLinesSync()) {
+        final RegExpMatch? match = pathLine.firstMatch(line);
+        if (match != null) {
+          submodulePaths.add(repoRoot.childDirectory(match.group(1)!.trim()));
+        }
+      }
+    }
+    return submodulePaths;
+  }
 }
 
 enum _LicenseFailureType { incorrectFirstParty, unknownThirdParty }

script/tool/lib/src/main.dart

@@ -28,6 +28,7 @@ import 'publish_plugin_command.dart';
 import 'pubspec_check_command.dart';
 import 'readme_check_command.dart';
 import 'test_command.dart';
+import 'update_excerpts_command.dart';
 import 'version_check_command.dart';
 import 'xcode_analyze_command.dart';
 
@@ -68,6 +69,7 @@ void main(List<String> args) {
     ..addCommand(PubspecCheckCommand(packagesDir))
     ..addCommand(ReadmeCheckCommand(packagesDir))
     ..addCommand(TestCommand(packagesDir))
+    ..addCommand(UpdateExcerptsCommand(packagesDir))
     ..addCommand(VersionCheckCommand(packagesDir))
     ..addCommand(XcodeAnalyzeCommand(packagesDir));