This converts existing ## Sample code samples to {@tool sample}...{@end-tool} form.
Also:
1. Fixed a minor bug in analyze-sample-code.dart
2. Made the snippet tool only insert descriptions if the description is non-empty.
3. Moved the Card diagram to before the code sample.
When converting all of the samples to use the snippet tool, I encountered some bugs/shortcomings:
1. The document production took 90 minutes, since the snippet tool was being invoked from the command line each time. I fixed this by snapshotting the executable before running, so it's down to 7 minutes.
2. The sample code was not being properly escaped by the snippet tool, so generics were causing issues in the HTML output. It is now quoted.
3. Code examples that used languages other than Dart were not supported. Anything that highlight.js was compiled for dartdoc with is now supported.
4. The comment color for highlight.js was light grey on white, which was pretty unreadable. It's now dark green and bold.
This rewrites the sample code analysis script to be a little less of a hack (but still not pretty), and to handle snippets as well.
It also changes the semantics of how sample code is handled: the namespace for the sample code is now limited to the file that it appears in, so some additional "Examples can assume:" blocks were added. The upside of this is that there will be far fewer name collisions.
I fixed the output too: no longer will you get 4000 lines of numbered output with the error at the top and have to grep for the actual problem. It gives the filename and line number of the original location of the code (in the comment in the tree), and prints out the source code on the line that caused the problem along with the error.
For snippets, it prints out the location of the start of the snippet and the source code line that causes the problem. It can't print out the original line, because snippets get formatted when they are written, so the line might not be in the same place.
This adds flutter create --sample which allows users to execute a command which will create a working sample app from samples embedded in the API docs.
The command looks something like this:
flutter create --sample=chip.DeletableChipAttributes.onDeleted mysample
This creates a custom dartdoc tool that will generate snippet blocks in our API docs that allow the user to copy easily to the clipboard, and will also embed the snippet code into a template to show it in a larger context with an app.
This PR adds the snippet tool, a template, and a couple of HTML skeleton files, one for snippets that are designed to be in an application setting, and one where it simply puts a nice container around existing snippets, making them easier to copy to the clipboard.
