Support for viewing and running Flutter documentation code samples

[pq]

A meta-issue to track sample creation (e.g., flutter create -sample) and execution from the IDE.

Flutter

• support for enumerating template sample ids Support for enumerating template sample ids flutter#25461
  • PR: Write snippets index file when generating docs flutter#25515

IDEA / IntelliJ

• support for creating sample content in the New Project Wizard (IDEA) Support for creating sample content in the New Project Wizard (IDEA) #2974
• support for creating sample content in the New Project Wizard (Android Studio) Support for creating sample content in the New Project Wizard (AS) #2975
• banner notifications for source files containing runnable samples (IDEA) Banner notifications for source files containing runnable samples #2976
  • (in Android Studio) (Android Studio) Banner notifications for source files containing runnable samples #3143

VSCode

• support creating Flutter docs sample applications (meta) Support creating Flutter docs sample applications Dart-Code/Dart-Code#1356

[DanTup]

I've opened Dart-Code/Dart-Code#1356 for the VS Code work.

[pq]

Besides being able to generate sample content from the new project wizard (which I expect could have a UI similar to the way we support stagehand templates), we should explore other ways to surface samples. Existing dartdoc support is a little basic so it's not obvious what we can do there without a bunch of work on the Dart Plugin, but we should consider it? For example, here's the "quick documentation" view for AppBar which has an associated sample.

There could be a link or some kind of affordance to create a sample from the docs. (The question remains though if anyone would find it since I'm not sure how well used that view is...)

/cc @jacob314 @InMatrix

@alexander-doroshko : do you have any analytics on how used the quick doc view is?

[pq]

Ah, and here's a mock of how sample creation from the new wizard might look:

[InMatrix]

(The question remains though if anyone would find it since I'm not sure how well used that view is...)

My impression is Quick Documentation a little bit hard to discover by users new to IntelliJ. In contrast, VS Code shows Quick Documentation anytime the mouse cursor is on a class name or method name.

I suspect we need to provide two entry points for running sample code in API docs: one from Flutter's API references on docs.flutter.io, and another one from within the IDE when the user checks documentation in the source code. For the latter, maybe the IDE can show a banner notification when the source file contains a runnable sample?

[DanTup]

For the latter, maybe the IDE can show a banner notification when the source file contains a runnable sample?

For VS Code, if microsoft/vscode#65269 gets fixed, then rather than potentially spamming with banners, we could inject links into the hovers that say "Open sample in VS Code", that when clicked will spawn a new VS Code window that automatically downloads the sample ready to run. I think that could be a nice experience?

[InMatrix]

Sounds good to me, @DanTup.

[alexander-doroshko]

do you have any analytics on how used the quick doc view is?

I don't have analytics in hands right now. I think everyone uses it every day, don't you? ;)
IntelliJ does have an option to show docs on hover but it's disabled by default.

[DanTup]

I tested out the VS Code protocol handler, and the rest of it works great. For ex. if Dart-Code/Dart-Code#1358 is landed, we can link to vscode://Dart-Code.dart-code/flutter/sample/material.AppBar.actions (both on the web and hopefully in hovers if the bug above is fixed) and it'll create the sample project (similar to how Flutter: New Project works).

If we get the ability to enumerate the full list, I can also add in a command that lets you select one.

[pq]

I suspect we need to provide two entry points for running sample code in API docs: one from Flutter's API references on docs.flutter.io, and another one from within the IDE when the user checks documentation in the source code.

Unfortunately, I don't think a protocol handler is straight-forward in IntelliJ (see e.g., https://youtrack.jetbrains.com/issue/IDEA-65879).

Failing a one-click solution I suppose we could introduce an action that uses clipboard content and then the flow could be:

1. copy id to clipboard (in browser)
2. invoke "Create sample from clipboard..." action (in IDEA)

🤔

@alexander-doroshko: any thoughts or experience here?

For the latter, maybe the IDE can show a banner notification when the source file contains a runnable sample?

A banner in IntelliJ I think this is a great idea. 👍

[alexander-doroshko]

I don't think IDEA-65879 is directly related. Are you thinking about links handling in Quick Doc popup? ExternalDocumentationHandler.handleExternalLink() allows doing that. what do you want to happen on click?

the source file contains a runnable sample

What does it technically mean?
And what does a 'sample' mean: a piece of code, a single file or a bunch of files?

[pq]

@alexander-doroshko: we're talking about support for url handling so that you could click a link, for example, in chrome (not quick docs) where you're browsing for example https://docs.flutter.io/flutter/material/IconButton-class.html and have a new project created in the IDE.

What does it technically mean?
And what does a 'sample' mean: a piece of code, a single file or a bunch of files?

If you look at the IconButton class docs, you'll see:

The Flutter create command supports the creation of apps with sample content. This issue is about integrating that support into the IDE.

[pq]

As of #3143, MVP support is complete. Let's track ongoing polish in follow-up issues.

Thanks all! 👍