initial commit

Author: Salman A. Khilji

AUTHORS

@@ -0,0 +1,6 @@
+# Below is a list of people and organizations that have contributed
+# to this package. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google, LLC

CHANGELOG.md

@@ -0,0 +1,28 @@
+## 0.2.5
+
+* Make the `--template` argument optional for dartpad and sample samples.
+
+## 0.2.4
+
+* publish the extract_sample command.
+
+## 0.2.3
+
+* Fix sample ID generation to not generate IDs with invalid characters in them (e.g. a ":" in "dart:ui").
+
+## 0.2.2
+
+* Enable parsing of linked samples, add section markers to extracted samples.
+
+## 0.2.1
+
+* Format the sample output, so that it matches the existing tool in the Flutter repo.
+
+## 0.2.0
+
+* Make tool conformant with the tool in the Flutter repo in preparation for switching over.
+* Upgrade to latest analyzer release, 2.0.0.
+
+## 0.1.0
+
+* Initial version, ported and modified from the [snippets tool](https://github.com/flutter/flutter/tree/master/dev/snippets) in the Flutter repo.

LICENSE

@@ -0,0 +1,25 @@
+Copyright 2013 The Flutter Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,246 @@
+# 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/master/dev/snippets/config/skeletons/snippet.html).
+
+#### Analysis
+
+The
+[`analyze_sample_code.dart`](https://github.com/flutter/flutter/blob/master/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/master/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.
+
+#### Templates
+
+To support showing an entire app when you click on the right tab of the
+code sample UI, we have to be able to insert the `sample` or `dartpad` block
+into the template and instantiate the right parts.
+
+To do this, there is a [templates
+directory](https://github.com/flutter/flutter/blob/master/dev/snippets/config/templates)
+that
+contains a list of templates. These templates represent an entire app that the
+`sample` or `dartpad` can be placed into, basically a replacement for
+`lib/main.dart` in a flutter app package.
+
+For more information about how to create, use, or update templates, see the
+[templates README.md](https://github.com/flutter/flutter/blob/master/dev/snippets/config/templates/README.md).
+
+#### Analysis
+
+The `../bots/analyze_sample_code.dart` script finds code inside the `@tool
+sample` sections and uses the Dart analyzer to check them after applying the
+specified template.
+
+## 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/master/dev/snippets/config/skeletons/sample.html)
+samples, one for
+[dartpad](https://github.com/flutter/flutter/blob/master/dev/snippets/config/skeletons/dartpad-sample.html),
+and one for
+[snippet](https://github.com/flutter/flutter/blob/master/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.
+3. Once complete, check `./dev/docs/doc` to check your API documentation. The
+   search bar will not work locally, so open `./dev/docs/doc/index.html` to
+   navigate through the documentation, or search `./dev/docs/doc/flutter` for
+   your page of interest.
+
+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
+(master 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:
+
+```
+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.