Move snippets package back into flutter repo

[gspencergoog]

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

• Cannot generate docs with a local version of the snippets tool #144408
• Linux docs_test is failing, closing the tree #147609
• Move docs_test and docs_publish to bringup #147645

Tests

• Added snippets tests to the overall testing build.

[sigurdm]

Using global activate for running the documentation step was very messy to say the least. It modifies user-configuration to do a temporary setup.

I think there's more we can do for supporting concurrency with dart pub global run but I don't think it is the right solution for you.

An alternative to this PR if you want to keep snippets in a package would be to

• make snippets a dev-dependency in dev/tools/pubspec.yaml,
• compile it manually before running dartdoc.

Currently there is no really good way of resolving bin/<X>.dart given a package.
But it is not much more than searching package_config.json for the package name, and going relative from its rootUri.

[gspencergoog]

• make snippets a dev-dependency in dev/tools/pubspec.yaml.
• compile it manually before running dartdoc.

Can you clarify what this would look like @sigurdm? I don't know what the command would be that would generate the executable from a dev dependency on the tool. Do I need to create a new dart package that has a executable: clause and that package depends on snippets? And why would it be a dev dependency and not a dependency?

[goderbauer]

LGTM, but the analyzer is unhappy.

[goderbauer]

Can you also send a PR to delete the tool from https://github.com/flutter/assets-for-api-docs/tree/main/packages/snippets so we are not confused about the two copies?

Should we also mark https://pub.dev/packages/snippets as discontinued since we are probably not going to publish any new versions there?

[gspencergoog]

Can you also send a PR to delete the tool from flutter/assets-for-api-docs@main/packages/snippets so we are not confused about the two copies?

Yes, will do.

Should we also mark pub.dev/packages/snippets as discontinued since we are probably not going to publish any new versions there?

Yes, that too.

[auto-submit]

auto label is removed for flutter/flutter/147690, due to - The status or check suite Google testing has failed. Please fix the issues identified (or deflake) before re-applying this label.

[sigurdm]

Can you clarify what this would look like @sigurdm? I don't know what the command would be that would generate the executable from a dev dependency on the tool. Do I need to create a new dart package that has a executable: clause and that package depends on snippets? And why would it be a dev dependency and not a dependency?

Yeah - that's the trouble, I don't think we currently have a command that will do it. (Hopefully we'll get that soon)

More details:

I would

• make snippets a dev-dependency in dev/tools/pubspec.yaml,
• (in Dart code, in the docs script before running dartdoc)
  • load package_config.json (via https://api.dart.dev/stable/3.3.4/dart-isolate/Isolate/packageConfigSync.html)
  • decode the json
  • iterate config['packages'] to find the entry named 'snippets'.
  • Join the snippets['rootDir'] with 'bin/snippets.dart' => snippetDart.
  • compile that file by invoking Process.runSync(Platform.resolvedExecutable, ['--snapshot', outputLocation, snippetDart])