Docs update (#148)

* Update docs

* Update docs

Author: subfuzion

docs/README.md

@@ -1,11 +1,26 @@
 # Functions Framework for Dart
 
+These docs will help you get started with the [Functions Framework for Dart],
+an open source **FaaS** (Function as a Service) framework that lets you write
+and deploy lightweight, event-driven functions.
+
 ## Contents
 
-[1 Introduction](01-introduction.md)  
-[2 Quickstart: Dart](quickstarts/01-quickstart-dart.md)  
-[3 Quickstart: Docker](quickstarts/02-quickstart-docker.md)  
-[4 Quickstart: Cloud Run](quickstarts/03-quickstart-cloudrun.md)  
+[Introduction](01-introduction.md)  
+
+### Setting up
+
+[Install dartfn](quickstarts/00-install-dartfn.md)
+
+### Quickstarts
+
+[Quickstart: Dart](quickstarts/01-quickstart-dart.md)  
+[Quickstart: Docker](quickstarts/02-quickstart-docker.md)  
+[Quickstart: Cloud Run](quickstarts/03-quickstart-cloudrun.md)  
 
 ---
 [[next]](01-introduction.md)
+
+<!-- Reference links -->
+[functions framework for dart]:
+https://github.com/GoogleCloudPlatform/functions-framework-dart

docs/quickstarts/00-install-dartfn.md

@@ -0,0 +1,100 @@
+# Installing and using dartfn
+
+`dartfn` is a command-line (CLI) tool for working with Dart Functions Framework
+projects. In this early version of the tool, you can use it to generate sample
+projects from templates. Currently there are three templates:
+
+- helloworld - a basic HTTP handler function
+- json - a simple function handler that accepts and sends JSON
+- cloudevent - a simple cloudevent function handler
+
+## Prerequisites
+
+- [Dart SDK] v2.10+
+
+## Install dartfn
+
+To install `dartfn` on your machine, run the following command:
+
+```shell
+dart pub global activate dartfn
+```
+
+Output
+
+```text
+dart pub global activate functions_framework_tool
+Resolving dependencies... (1.2s)
+...
+Precompiling executables... (1.1s)
+Precompiled functions_framework_tool:dartfn.
+Installed executable dartfn.
+Activated functions_framework_tool 0.3.0.
+```
+
+## Using dartfn
+
+### List available generators
+
+```shell
+dartfn generate --list
+```
+
+Output
+
+```text
+Available generators:
+cloudevent - A sample Functions Framework project for handling a cloudevent.
+helloworld - A sample "Hello, World!" Functions Framework project.
+json       - A sample Functions Framework project for handling JSON.
+```
+
+### Generate a project
+
+Generate a `helloworld` project, for example:
+
+```shell
+mkdir helloworld
+cd helloworld
+dartfn generate helloworld
+```
+
+Output
+
+```text
+project: demo
+Creating helloworld application `ex`:
+  demo/.gitignore
+  demo/Dockerfile
+  demo/README.md
+  demo/analysis_options.yaml
+  demo/bin/server.dart
+  demo/lib/functions.dart
+  demo/pubspec.yaml
+  demo/test/function_test.dart
+8 files written.
+
+--> to provision required packages, run 'pub get'
+```
+
+### Get the new project package dependencies
+
+```shell
+dart pub get
+```
+
+Output
+
+```text
+Resolving dependencies... (2.1s)
+...
+Changed 74 dependencies!
+```
+
+---
+[[toc]](../README.md)
+[[back]](../01-introduction.md)
+[[next]](01-quickstart-dart.md)
+
+<!-- reference links -->
+[Dart SDK]: https://dart.dev/get-dart

docs/quickstarts/01-quickstart-dart.md

@@ -10,8 +10,12 @@ normal developer workflow.
 
 ## Get a copy of the `hello` example
 
-Clone this repo or download a [zip] archive and extract the contents. Change
-directory to `examples/hello`.
+You can either
+
+* Run `dartfn` to create a new project using the `helloworld` generator (see
+  [Installing and using dartfn])
+* Clone this repo or download a [zip] archive and extract the contents
+  * Change directory to `examples/hello`.
 
 ## Build the example
 
@@ -159,12 +163,13 @@ Listening on :8080
 
 ---
 [[toc]](../README.md)
-[[back]](../01-introduction.md)
+[[back]](00-install-dartfn.md)
 [[next]](02-quickstart-docker.md)
 
 <!-- reference links -->
 [curl]: https://curl.se/docs/manual.html
 [Dart SDK]: https://dart.dev/get-dart
+[Installing and using dartfn]: 00-install-dartfn.md
 [Request]: https://pub.dev/documentation/shelf/latest/shelf/Request-class.html
 [Response]: https://pub.dev/documentation/shelf/latest/shelf/Response-class.html
 [Shelf]: https://pub.dev/packages/shelf

docs/quickstarts/02-quickstart-docker.md

@@ -13,8 +13,12 @@ environment.
 
 ## Get a copy of the `hello` example
 
-Clone this repo or download a [zip] archive and extract the contents. Change
-directory to `examples/hello`.
+You can either
+
+* Run `dartfn` to create a new project using the `helloworld` generator (see
+  [Installing and using dartfn])
+* Clone this repo or download a [zip] archive and extract the contents
+  * Change directory to `examples/hello`.
 
 ## Build a Docker image
 
@@ -203,4 +207,5 @@ docker image rm hellofunc   # remove the image
 
 <!-- reference links -->
 [docker]: https://docs.docker.com/get-docker/
+[Installing and using dartfn]: 00-install-dartfn.md
 [zip]: https://github.com/GoogleCloudPlatform/functions-framework-dart/archive/main.zip

docs/quickstarts/03-quickstart-cloudrun.md

@@ -46,8 +46,10 @@ Updated property [core/project].
 
 ## Get a copy of the `hello` example
 
-Clone this repo or download a [zip] archive and extract the contents. Change
-directory to `examples/hello`.
+* Run `dartfn` to create a new project using the `helloworld` generator (see
+  [Installing and using dartfn])
+* Clone this repo or download a [zip] archive and extract the contents
+  * Change directory to `examples/hello`.
 
 ## Build and deploy with a single command
 
@@ -164,6 +166,7 @@ the [Manage resources] page.
 [gcloud]: https://cloud.google.com/sdk/docs/install
 [Google Cloud]: https://cloud.google.com/gcp
 [incur charges]: https://cloud.google.com/container-registry/pricing
+[Installing and using dartfn]: 00-install-dartfn.md
 [Manage resources]: https://console.cloud.google.com/iam-admin/projects
 [project selector]: https://console.cloud.google.com/projectselector2/home/dashboard
 [quickstart]: https://cloud.google.com/sdk/docs/quickstart

functions_framework_tool/README.md

@@ -7,9 +7,9 @@ In this early iteration, a CLI tool (`dartfn`) is provided with a `generate`
 command for scaffolding new projects into an empty directory. Three initial
 generator templates are available:
 
-* helloworld - a basic HTTP handler function
-* json - a simple function handler that accepts and sends JSON
-* cloudevent - a simple cloudevent function handler
+- helloworld - a basic HTTP handler function
+- json - a simple function handler that accepts and sends JSON
+- cloudevent - a simple cloudevent function handler
 
 To install the `dartfn` tool on your machine, run the following command:
 
@@ -123,4 +123,3 @@ Output
 ```text
 0.3.1
 ```
-