Move snippets package back into flutter repo (#147690)

## Description

This moves the snippets package back into the Flutter repo so that API documentation generation can happen without the use of `dart pub global run` because `pub run` doesn't handle concurrency well.

The change modifies the dartdoc building process to include building an executable from the snippets tool and installing that in the cache directory for use during docs generation.

The snippets tool will reside in dev/snippets, where it originally resided before being moved to https://github.com/flutter/assets-for-api-docs.

The snippets code itself is unchanged from the code that is in https://github.com/flutter/assets-for-api-docs/packages/snippets.

## Related Issues
 - #144408
 - #147609
 - #147645

## Tests
 - Added snippets tests to the overall testing build.

dartdoc_options.yaml

@@ -5,13 +5,13 @@ dartdoc:
   # The dev/bots/docs.sh script does this automatically.
   tools:
     snippet:
-      command: ["bin/cache/dart-sdk/bin/dart", "pub", "global", "run", "snippets", "--output-directory=doc/snippets", "--type=snippet"]
+      command: ["bin/cache/artifacts/snippets/snippets", "--output-directory=doc/snippets", "--type=snippet"]
       description: "Creates sample code documentation output from embedded documentation samples."
     sample:
-      command: ["bin/cache/dart-sdk/bin/dart", "pub", "global", "run", "snippets", "--output-directory=doc/snippets", "--type=sample"]
+      command: ["bin/cache/artifacts/snippets/snippets", "--output-directory=doc/snippets", "--type=sample"]
       description: "Creates full application sample code documentation output from embedded documentation samples."
     dartpad:
-      command: ["bin/cache/dart-sdk/bin/dart", "pub", "global", "run", "snippets", "--output-directory=doc/snippets", "--type=dartpad"]
+      command: ["bin/cache/artifacts/snippets/snippets", "--output-directory=doc/snippets", "--type=dartpad"]
       description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
   errors:
     ## Default errors of dartdoc:

dev/bots/docs.sh

@@ -107,16 +107,25 @@ function parse_args() {
   fi
 }
 
+function build_snippets_tool() (
+  local snippets_dir="$FLUTTER_ROOT/dev/snippets"
+  local output_dir="$FLUTTER_BIN/cache/artifacts/snippets"
+  echo "Building snippets tool executable."
+  command cd "$snippets_dir"
+  mkdir -p "$output_dir"
+  dart pub get
+  dart compile exe -o "$output_dir/snippets" bin/snippets.dart
+)
+
 function generate_docs() {
     # Install and activate dartdoc.
     # When updating to a new dartdoc version, please also update
     # `dartdoc_options.yaml` to include newly introduced error and warning types.
     "$DART" pub global activate dartdoc 8.0.6
 
-    # Install and activate the snippets tool, which resides in the
-    # assets-for-api-docs repo:
-    # https://github.com/flutter/assets-for-api-docs/tree/main/packages/snippets
-    "$DART" pub global activate snippets 0.4.3
+    # Build and install the snippets tool, which resides in
+    # the dev/docs/snippets directory.
+    build_snippets_tool
 
     # This script generates a unified doc set, and creates
     # a custom index.html, placing everything into DOC_DIR.

dev/bots/test.dart

@@ -146,6 +146,7 @@ Future<void> main(List<String> args) async {
       'customer_testing': customerTestingRunner,
       'analyze': analyzeRunner,
       'fuchsia_precache': fuchsiaPrecacheRunner,
+      'snippets': _runSnippetsTests,
       'docs': docsRunner,
       'verify_binaries_codesigned': verifyCodesignedTestRunner,
       kTestHarnessShardName: testHarnessTestsRunner, // Used for testing this script; also run as part of SHARD=framework_tests, SUBSHARD=misc.
@@ -236,6 +237,21 @@ Future<void> _runToolTests() async {
   });
 }
 
+Future<void> _runSnippetsTests() async {
+  final String snippetsPath = path.join(flutterRoot, 'dev', 'snippets');
+  final List<String> allTests = Directory(path.join(snippetsPath, 'test'))
+      .listSync(recursive: true).whereType<File>()
+      .map<String>((FileSystemEntity entry) => path.relative(entry.path, from: _toolsPath))
+      .where((String testPath) => path.basename(testPath).endsWith('_test.dart')).toList();
+
+  await runDartTest(
+    snippetsPath,
+    forceSingleCore: true,
+    testPaths: selectIndexOfTotalSubshard<String>(allTests),
+    collectMetrics: true,
+  );
+}
+
 Future<void> runForbiddenFromReleaseTests() async {
   // Build a release APK to get the snapshot json.
   final Directory tempDirectory = Directory.systemTemp.createTempSync('flutter_forbidden_imports.');

dev/snippets/README.md

@@ -0,0 +1,231 @@
+# Dartdoc Sample Generation
+
+The Flutter API documentation contains code blocks that help provide context or
+a good starting point when learning to use any of Flutter's APIs.
+
+To generate these code blocks, Flutter uses dartdoc tools to turn documentation
+in the source code into API documentation, as seen on [https://api.flutter.dev/]
+
+## Table of Contents
+
+- [Types of code blocks](#types-of-code-blocks)
+  - [Snippet tool](#snippet-tool)
+  - [Sample tool](#sample-tool)
+- [Skeletons](#skeletons)
+- [Test Doc Generation Workflow](#test-doc-generation-workflow)
+
+## Types of code blocks
+
+There are three kinds of code blocks.
+
+- A `snippet`, which is a more or less context-free code snippet that we
+  magically determine how to analyze.
+
+- A `dartpad` sample, which gets placed into a full-fledged application, and can
+  be executed inline in the documentation on the web page using
+  DartPad.
+
+- A `sample`, which gets placed into a full-fledged application, but isn't
+  placed into DartPad in the documentation because it doesn't make sense to do
+  so.
+
+Ideally, every sample is a DartPad sample, but some samples don't have any visual
+representation and some just don't make sense that way (for example, sample
+code for setting the system UI's notification area color on Android won't do
+anything on the web).
+
+### Snippet Tool
+
+![Code snippet image](assets/code_snippet.png)
+
+The code `snippet` tool generates a block containing a description and example
+code. Here is an example of the code `snippet` tool in use:
+
+```dart
+/// {@tool snippet}
+///
+/// If the avatar is to have an image, the image should be specified in the
+/// [backgroundImage] property:
+///
+/// ```dart
+/// CircleAvatar(
+///   backgroundImage: NetworkImage(userAvatarUrl),
+/// )
+/// ```
+/// {@end-tool}
+```
+
+This will generate sample code that can be copied to the clipboard and added to
+existing applications.
+
+This uses the skeleton for `snippet` snippets when generating the HTML to put
+into the Dart docs. You can find this [template in the Flutter
+repo](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/snippet.html).
+
+#### Analysis
+
+The
+[`analyze_sample_code.dart`](https://github.com/flutter/flutter/blob/main/dev/bots/analyze_sample_code.dart)
+script finds code inside the `@tool
+snippet` sections and uses the Dart analyzer to check them.
+
+There are several kinds of sample code you can specify:
+
+- Constructor calls, typically showing what might exist in a build method. These
+  will be inserted into an assignment expression assigning to a variable of type
+  "dynamic" and followed by a semicolon, for analysis.
+
+- Class definitions. These start with "class", and are analyzed verbatim.
+
+- Other code. It gets included verbatim, though any line that says `// ...` is
+  considered to separate the block into multiple blocks to be processed
+  individually.
+
+The above means that it's tricky to include verbatim imperative code (e.g. a
+call to a method) since it won't be valid to have such code at the top level.
+Instead, wrap it in a function or even a whole class, or make it a valid
+variable declaration.
+
+You can declare code that should be included in the analysis but not shown in
+the API docs by adding a comment "// Examples can assume:" to the file (usually
+at the top of the file, after the imports), following by one or more
+commented-out lines of code. That code is included verbatim in the analysis. For
+example:
+
+```dart
+// Examples can assume:
+// final BuildContext context;
+// final String userAvatarUrl;
+```
+
+You can assume that the entire Flutter framework and most common
+`dart:*` packages are imported and in scope; `dart:math` as `math` and
+`dart:ui` as `ui`.
+
+### Sample Tool
+
+![Code sample image](assets/code_sample.png)
+
+The code `sample` and `dartpad` tools can expand sample code into full Flutter
+applications. These sample applications can be directly copied and used to
+demonstrate the API's functionality in a sample application, or used with the
+`flutter create` command to create a local project with the sample code. The
+`dartpad` samples are embedded into the API docs web page and are live
+applications in the API documentation.
+
+```dart
+/// {@tool sample --template=stateless_widget_material}
+/// This example shows how to make a simple [FloatingActionButton] in a
+/// [Scaffold], with a pink [backgroundColor] and a thumbs up [Icon].
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return Scaffold(
+///     appBar: AppBar(
+///       title: Text('Floating Action Button Sample'),
+///     ),
+///     body: Center(
+///       child: Text('Press the button below!')
+///     ),
+///     floatingActionButton: FloatingActionButton(
+///       onPressed: () {
+///         // Add your onPressed code here!
+///       },
+///       child: Icon(Icons.thumb_up),
+///       backgroundColor: Colors.pink,
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+```
+
+This uses the skeleton for [application](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/sample.html)
+snippets in the Flutter repo.
+
+The `sample` and `dartpad` tools also allow for quick Flutter app generation
+using the following command:
+
+```bash
+flutter create --sample=[directory.File.sampleNumber] [name_of_project_directory]
+```
+
+This command is displayed as part of the sample in the API docs.
+
+#### Sample Analysis
+
+The [`../bots/analyze_sample_code.dart`](../bots/analyze_sample_code.dart)
+script finds code inside the `@tool sample` sections and uses the Dart analyzer
+to check the sample code.
+
+## Skeletons
+
+A skeleton (concerning this tool) is an HTML template into which the Dart
+code blocks and descriptions are interpolated.
+
+There is currently one skeleton for
+[application](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/sample.html)
+samples, one for
+[dartpad](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/dartpad-sample.html),
+and one for
+[snippet](https://github.com/flutter/flutter/blob/main/dev/snippets/config/skeletons/snippet.html)
+code samples, but there could be more.
+
+Skeletons use mustache notation (e.g. `{{code}}`) to mark where components will
+be interpolated into the template. It doesn't use the mustache
+package since these are simple string substitutions, but it uses the same
+syntax.
+
+The code block generation tools that process the source input and emit HTML for
+output, which dartdoc places back into the documentation. Any options given to
+the `{@tool ...}` directive are passed on verbatim to the tool.
+
+The `snippets` tool renders these examples through a combination of markdown
+and HTML using the `{@inject-html}` dartdoc directive.
+
+## Test Doc Generation Workflow
+
+If you are making changes to an existing code block or are creating a new code
+block, follow these steps to generate a local copy of the API docs and verify
+that your code blocks are showing up correctly:
+
+1. Make an update to a code block or create a new code block.
+2. From the root directory, run `./dev/bots/docs.sh`. This should start
+   generating a local copy of the API documentation.
+   Supplying the "--output" argument allows you to specify the output zip file
+   for the completed documentation. Defaults to `api_docs.zip`` in the current
+   directory.
+3. Once complete, unzip the files to the desired location and open the `index.html`
+   within.
+
+Note that generating the sample output will not allow you to run your code in
+DartPad, because DartPad pulls the code it runs from the appropriate docs server
+(main or stable).
+
+Copy the generated code and paste it into a regular DartPad instance to test if
+it runs in DartPad. To get the code that will be produced by your documentation
+changes, run sample analysis locally (see the next section) and paste the output
+into a DartPad at [https://dartpad.dartlang.org].
+
+## Running sample analysis locally
+
+If all you want to do is analyze the sample code you have written locally, then
+generating the entire docs output takes a long time.
+
+Instead, you can run the analysis locally with this command from the Flutter root:
+
+```bash
+TMPDIR=/tmp bin/cache/dart-sdk/bin/dart dev/bots/analyze_sample_code.dart --temp=samples
+```
+
+This will analyze the samples, and leave the generated files in `/tmp/samples`
+
+You can find the sample you are working on in `/tmp/samples`. It is named using the
+path to the file it is in, and the line of the file that the `{@tool ...}` directive
+is on.
+
+For example, the file `sample.src.widgets.animated_list.52.dart` points to the sample
+in `packages/flutter/src/widgets/animated_list.dart` at line 52. You can then take the
+contents of that file, and paste it into [Dartpad](https://dartpad.dev) and see if it
+works. If the sample relies on new features that have just landed, it may not work
+until the features make it into the `dev` branch.