From 48ec54734a7cb0052aaf4681257fe6d2c65d1bfd Mon Sep 17 00:00:00 2001 From: Tony Pujals Date: Wed, 23 Dec 2020 15:29:37 -0800 Subject: [PATCH 1/2] Update docs --- docs/README.md | 23 ++++-- docs/quickstarts/00-install-dartfn.md | 99 ++++++++++++++++++++++++++ docs/quickstarts/01-quickstart-dart.md | 11 ++- functions_framework_tool/README.md | 6 +- 4 files changed, 129 insertions(+), 10 deletions(-) create mode 100644 docs/quickstarts/00-install-dartfn.md diff --git a/docs/README.md b/docs/README.md index b77c420a..e9c499fb 100644 --- a/docs/README.md +++ b/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) + + +[functions framework for dart]: +https://github.com/GoogleCloudPlatform/functions-framework-dart diff --git a/docs/quickstarts/00-install-dartfn.md b/docs/quickstarts/00-install-dartfn.md new file mode 100644 index 00000000..453a99e8 --- /dev/null +++ b/docs/quickstarts/00-install-dartfn.md @@ -0,0 +1,99 @@ +# 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) + + +[Dart SDK]: https://dart.dev/get-dart diff --git a/docs/quickstarts/01-quickstart-dart.md b/docs/quickstarts/01-quickstart-dart.md index bb232593..5e0da48b 100644 --- a/docs/quickstarts/01-quickstart-dart.md +++ b/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) [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 diff --git a/functions_framework_tool/README.md b/functions_framework_tool/README.md index 483e12fb..2a42d6ff 100644 --- a/functions_framework_tool/README.md +++ b/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: From fe22ff31de54b3577685b10f7fc6d256bbc396da Mon Sep 17 00:00:00 2001 From: Tony Pujals Date: Wed, 23 Dec 2020 15:39:22 -0800 Subject: [PATCH 2/2] Update docs --- docs/quickstarts/00-install-dartfn.md | 5 +++-- docs/quickstarts/01-quickstart-dart.md | 6 +++--- docs/quickstarts/02-quickstart-docker.md | 9 +++++++-- docs/quickstarts/03-quickstart-cloudrun.md | 7 +++++-- functions_framework_tool/README.md | 1 - 5 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/quickstarts/00-install-dartfn.md b/docs/quickstarts/00-install-dartfn.md index 453a99e8..511360ad 100644 --- a/docs/quickstarts/00-install-dartfn.md +++ b/docs/quickstarts/00-install-dartfn.md @@ -1,6 +1,6 @@ # Installing and using dartfn -`dartfn` is a command-line (CLI) tool for working with Dart Functions Framework +`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: @@ -10,7 +10,7 @@ projects from templates. Currently there are three templates: ## Prerequisites -* [Dart SDK] v2.10+ +- [Dart SDK] v2.10+ ## Install dartfn @@ -41,6 +41,7 @@ dartfn generate --list ``` Output + ```text Available generators: cloudevent - A sample Functions Framework project for handling a cloudevent. diff --git a/docs/quickstarts/01-quickstart-dart.md b/docs/quickstarts/01-quickstart-dart.md index 5e0da48b..1c768045 100644 --- a/docs/quickstarts/01-quickstart-dart.md +++ b/docs/quickstarts/01-quickstart-dart.md @@ -12,10 +12,10 @@ normal developer workflow. You can either -- Run `dartfn` to create a new project using the `helloworld` generator (see +* 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`. +* Clone this repo or download a [zip] archive and extract the contents + * Change directory to `examples/hello`. ## Build the example diff --git a/docs/quickstarts/02-quickstart-docker.md b/docs/quickstarts/02-quickstart-docker.md index dc8d307a..682f8a89 100644 --- a/docs/quickstarts/02-quickstart-docker.md +++ b/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 [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 diff --git a/docs/quickstarts/03-quickstart-cloudrun.md b/docs/quickstarts/03-quickstart-cloudrun.md index 88d0cf20..92eb089e 100644 --- a/docs/quickstarts/03-quickstart-cloudrun.md +++ b/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 diff --git a/functions_framework_tool/README.md b/functions_framework_tool/README.md index 2a42d6ff..2205c0c3 100644 --- a/functions_framework_tool/README.md +++ b/functions_framework_tool/README.md @@ -123,4 +123,3 @@ Output ```text 0.3.1 ``` -