openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From daisy...@apache.org
Subject [incubator-openwhisk-wskdeploy] branch master updated: Update Programming Guide - part7 (#555)
Date Tue, 26 Sep 2017 05:21:51 GMT
This is an automated email from the ASF dual-hosted git repository.

daisyguo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git


The following commit(s) were added to refs/heads/master by this push:
     new 03c87f1  Update Programming Guide - part7 (#555)
03c87f1 is described below

commit 03c87f16c7ed26b699975ed3b7a7bef7dc7ca9c1
Author: Matt Rutkowski <mrutkows@us.ibm.com>
AuthorDate: Tue Sep 26 00:21:49 2017 -0500

    Update Programming Guide - part7 (#555)
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * Adding more use cases; improving guide structure.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
    
    * adding more Action examples with diff paramter variants.
---
 docs/examples/manifest_hello_world.yaml            |  2 +-
 docs/examples/manifest_hello_world_3.yaml          | 20 -----
 .../manifest_hello_world_advanced_parms.yaml       | 29 +++++++
 .../examples/manifest_hello_world_fixed_parms.yaml | 11 +++
 ....yaml => manifest_hello_world_typed_parms.yaml} |  6 +-
 docs/programming_guide.md                          | 24 ++++--
 docs/wskdeploy_action_advanced_parms.md            | 93 +++++++++++++++++++++
 docs/wskdeploy_action_fixed_parms.md               | 74 +++++++++++++++++
 docs/wskdeploy_action_helloworld.md                | 86 +++++++++++++++++++
 docs/wskdeploy_action_typed_parms.md               | 84 +++++++++++++++++++
 docs/wskdeploy_faq.md                              | 11 +++
 docs/wskdeploy_hello_world.md                      | 77 -----------------
 docs/wskdeploy_helloworld_advanced_parms.md        | 64 --------------
 docs/wskdeploy_helloworld_basic_parms.md           | 59 -------------
 docs/wskdeploy_package_minimal.md                  | 97 ++++++++++++++++++++++
 docs/wskdeploy_packages.md                         | 94 ---------------------
 docs/wskdeploy_triggerrule_basic.md                | 59 +++++++++++++
 17 files changed, 566 insertions(+), 324 deletions(-)

diff --git a/docs/examples/manifest_hello_world.yaml b/docs/examples/manifest_hello_world.yaml
index 34944fa..b71e5f1 100644
--- a/docs/examples/manifest_hello_world.yaml
+++ b/docs/examples/manifest_hello_world.yaml
@@ -1,4 +1,4 @@
-# Example 1: Basic Hello World using NodeJS (JavaScript)
+# Example: Basic Hello World using a NodeJS (JavaScript) action
 package:
   name: hello_world_package
   version: 1.0
diff --git a/docs/examples/manifest_hello_world_3.yaml b/docs/examples/manifest_hello_world_3.yaml
deleted file mode 100644
index 1e7d9d5..0000000
--- a/docs/examples/manifest_hello_world_3.yaml
+++ /dev/null
@@ -1,20 +0,0 @@
-# Example 3: inputs and output parameters with explicit types and descriptions
-package:
-  name: hello_world_package
-  version: 1.0
-  license: Apache-2.0
-  actions:
-    hello_world_3:
-      function: src/hello/hello.js
-      runtime: nodejs@6
-      inputs:
-        name:
-          type: string
-          description: name of person
-        place:
-          type: string
-          description: location of person
-      outputs:
-        greeting:
-          type: string
-          description: greeting string
diff --git a/docs/examples/manifest_hello_world_advanced_parms.yaml b/docs/examples/manifest_hello_world_advanced_parms.yaml
new file mode 100644
index 0000000..a727ff7
--- /dev/null
+++ b/docs/examples/manifest_hello_world_advanced_parms.yaml
@@ -0,0 +1,29 @@
+# Example: input and output parameters with advanced fields
+package:
+  name: hello_world_package
+  ... # Package keys omitted for brevity
+  actions:
+    hello_world_advanced_parms:
+      function: src/hello/hello.js
+      runtime: nodejs@6
+      inputs:
+        name:
+          type: string
+          description: name of person
+          value: Sam
+        place:
+          type: string
+          description: location of person
+          default: unknown
+        children:
+          type: integer
+          description: Number of children
+          default: 0
+        height:
+          type: float
+          description: height in meters
+          default: 0.0
+      outputs:
+        greeting:
+          type: string
+          description: greeting string
diff --git a/docs/examples/manifest_hello_world_fixed_parms.yaml b/docs/examples/manifest_hello_world_fixed_parms.yaml
new file mode 100644
index 0000000..42751bb
--- /dev/null
+++ b/docs/examples/manifest_hello_world_fixed_parms.yaml
@@ -0,0 +1,11 @@
+# Example: “Hello world” with fixed input values for ‘name’ and ‘place’
+package:
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    hello_world_fixed_parms:
+      function: src/hello.js
+      inputs:
+        name: Sam
+        place: the Shire
diff --git a/docs/examples/manifest_hello_world_2.yaml b/docs/examples/manifest_hello_world_typed_parms.yaml
similarity index 56%
rename from docs/examples/manifest_hello_world_2.yaml
rename to docs/examples/manifest_hello_world_typed_parms.yaml
index f178ad4..4b1a58d 100644
--- a/docs/examples/manifest_hello_world_2.yaml
+++ b/docs/examples/manifest_hello_world_typed_parms.yaml
@@ -1,13 +1,15 @@
-# Example 2: “Hello world” with explicit input and output parameter declarations
+# Example: “Hello world” with explicit input and output parameter declarations
 package:
   name: hello_world_package
   version: 1.0
   license: Apache-2.0
   actions:
-    hello_world_2:
+    hello_world_typed_parms:
       function: src/hello.js
       inputs:
         name: string
         place: string
+        children: integer
+        height: float
       outputs:
         greeting: string
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index fd1c56b..0aa4489 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -4,13 +4,16 @@ _A step-by-step guide for deploying Apache OpenWhisk applications using
Package
 This guide will walk you through how to describe OpenWhisk applications and packages using
the [OpenWhisk Packaging Specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification#openwhisk-packaging-specification)
and deploy them through the Whisk Deploy (```wskdeploy```) utility. Please use the specification
as the ultimate reference for all Manifest file grammar and syntax.
 
 ## Getting started
+
 ### Setting up your Host and Credentials
 In order to deploy your OpenWhisk package, at minimum, the ```wskdeploy``` utility needs
valid OpenWhisk APIHOST and AUTH variable to attempt deployment. Please read the [Configuring
wskdeploy](wskdeploy_configuring.md#configuring-wskdeploy)
 
 ### Debugging your Package Manifests
-
 In addition to the normal output the ```wskdeploy``` utility provides, you may enable additional
information that may further assist you in debugging. Please read the [Debugging Whisk Deploy](wskdeploy_debugging.md#debugging-wskdeploy)
document.
 
+### FAQ for ```wskdeploy```
+Answers to Frequently Asked Questions may be found in the [wskdeploy utility FAQ](wskdeploy_faq.md).
+
 ---
 
 # Guided Examples
@@ -19,10 +22,17 @@ Below is the list of "guided examples" where you can start by "Creating
a 'hello
 
 Each example shows the "code", that is the Package Manifest, Deployment file and Actions
that will be used to deploy that application or package, as well as discusses the interesting
features the example is highlighting.
 
-- [Creating a minimal Package](wskdeploy_packages.md#packages) - creating a basic package
manifet and deploying it.
-- [Creating a "Hello World" package](wskdeploy_hello_world.md#creating-a-hello-world-package)
- deploy your first function using a manifest.
-- [Actions with Basic Parameters](wskdeploy_helloworld_basic_parms.md#actions-with-basic-parameters)
- declare named input and output parameters on an Action with their types.
-- [Actions with Advanced Parameters](wskdeploy_helloworld_advanced_parms.md#actions-with-advanced-parameters)
- input and output parameter declarations with more detailed information.
+- Package examples
+  - [Creating a minimal Package](wskdeploy_package_minimal.md#packages) - creating a basic
package manifest and deploying it.
+- Action examples
+  - [The "Hello World" Action](wskdeploy_action_helloworld.md#actions) - deploy a "hello
world" JavaScript function using a manifest.
+  - [Adding fixed input parameters](wskdeploy_action_fixed_parms.md#actions) - bind fixed
values to input parameters.
+  - [Typed Parameters](wskdeploy_action_typed_parms.md#actions) - declare named input and
output parameters on an Action with their types.
+  - [Advanced Parameters](wskdeploy_action_advanced_parms.md#actions) - input and output
parameter declarations with more detailed information.
+- Trigger and Rule examples
+  - [Basic Trigger and Rule](wskdeploy_triggerrule_basic.md#triggers-and-rules) - adding
a basic trigger and rule to the advanced Parameter "hello world".
+
+<!--     - [Declaring Runtime version]() - TBD -->
 
 ---
 <!--
@@ -33,8 +43,8 @@ Each example shows the "code", that is the Package Manifest, Deployment
file and
 <table align="center">
   <tr>
     <td><a>&lt;&lt;&nbsp;previous</a></td>
-    <td><a href="programming_guide.md#guided-examples">Index</a></td>
-    <td><a href="wskdeploy_packages.md#packages">next&nbsp;&gt;&gt;</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <td><a href="wskdeploy_package_minimal.md#packages">next&nbsp;&gt;&gt;</a></td>
   </tr>
 </table>
 </div>
diff --git a/docs/wskdeploy_action_advanced_parms.md b/docs/wskdeploy_action_advanced_parms.md
new file mode 100644
index 0000000..e166dcd
--- /dev/null
+++ b/docs/wskdeploy_action_advanced_parms.md
@@ -0,0 +1,93 @@
+# Actions
+
+## Advanced parameters
+
+This example builds on the previous [“Hello world" with typed input and output parameters](wskdeploy_action_typed_parms.md#actions)
example with more robust input and output parameter declarations by using a multi-line format
for declaration.
+
+This example:
+- shows how to declare input and output parameters on the action ‘```hello_world```’
using a multi-line grammar.
+- adds the ‘```name```’ and ‘```place```’ input parameters, both of type ‘```string```’,
to the ‘```hello_world``’ action each also includes an associated ‘```description```’
value.
+- adds the ‘```greeting```’ output parameter of explicit ‘```type```’ of ‘```string```’
to the ‘```hello_world```’ action with a ‘```description```’.
+
+### Manifest File
+
+If we want to do more than declare the type (i.e., ‘string’, ‘integer’, ‘float’,
etc.) of the input parameter, we can use the multi-line grammar.
+
+#### _Example: input and output parameters with explicit types and descriptions_
+```yaml
+package:
+  name: hello_world_package
+  ... # Package keys omitted for brevity
+  actions:
+    hello_world_advanced_parms:
+      function: src/hello/hello.js
+      runtime: nodejs@6
+      inputs:
+        name:
+          type: string
+          description: name of person
+          value: Sam
+        place:
+          type: string
+          description: location of person
+          default: unknown
+        children:
+          type: integer
+          description: Number of children
+          default: 0
+        height:
+          type: float
+          description: height in meters
+          default: 0.0
+      outputs:
+        greeting:
+          type: string
+          description: greeting string
+```
+
+### Deploying
+```sh
+$ wskdeploy -m docs/examples/manifest_hello_world_advanced_parms.yaml
+```
+
+### Invoking
+```sh
+$ wsk action invoke hello_world_package/hello_world_advanced_parms --blocking
+```
+
+### Result
+```sh
+"result": {
+    "greeting": "Hello, Sam from unknown"
+},
+```
+
+### Discussion
+Describing the input and output parameter types, descriptions, defaults and other data:
+- enables tooling to validate values users may input and prompt for missing values using
the descriptions provided.
+- allows verification that outputs of an Action are compatible with the expected inputs of
another Action so that they can be composed in a sequence.
+
+### Source code
+The manifest file for this example can be found here:
+- [manifest_hello_world_advanced_parms.yaml](examples/manifest_hello_world_advanced_parms.yaml)
+
+### Specification
+For convenience, the Actions and Parameters grammar can be found here:
+- **[Actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)**
+- **[Parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)**
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_action_typed_parms.md#actions">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <td><a href="wskdeploy_triggerrule_basic.md#triggers-and-rules">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_action_fixed_parms.md b/docs/wskdeploy_action_fixed_parms.md
new file mode 100644
index 0000000..e4a1be5
--- /dev/null
+++ b/docs/wskdeploy_action_fixed_parms.md
@@ -0,0 +1,74 @@
+# Actions
+
+## Adding fixed input parameters
+
+This example builds upon the previous “hello world” example and shows how fixed values
can be supplied to the input parameters of an Action.
+
+It shows how to:
+- Declare input parameters on the action ‘```hello_world```’ using a single-line grammar.
+- Add ‘```name```’ and ‘```place```’ as input parameters with the fixed values “```Sam```”
and “```the Shire```” respectively.
+
+### Manifest File
+
+#### _Example: “Hello world” with fixed input values for ‘name’ and ‘place’_
+```yaml
+package:
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    hello_world_fixed_parms:
+      function: src/hello.js
+      inputs:
+        name: Sam
+        place: the Shire
+```
+
+### Deploying
+```sh
+$ wskdeploy -m docs/examples/manifest_hello_world_fixed_parms.yaml
+```
+
+### Invoking
+```sh
+$ wsk action invoke hello_world_package/hello_world_fixed_parms --blocking
+```
+
+### Result
+```sh
+"result": {
+    "greeting": "Hello, Sam from the Shire"
+},
+```
+
+### Discussion
+
+In this example:
+- The value for the ‘```name```’ input parameter would be set to “```Sam```” and
+- The value for the ‘```place```’ input parameter would be set to “```the Shire```”.
+- The wskdeploy utility would infer both of their Types were '```string```'.
+
+### Source code
+The manifest file for this example can be found here:
+- [manifest_hello_world_fixed_parms.yaml](examples/manifest_hello_world_fixed_parms.yaml)
+
+### Specification
+For convenience, the Actions and Parameters grammar can be found here:
+- **[Actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)**
+- **[Parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)**
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <td><a href="wskdeploy_action_typed_parms.md#actions">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_action_helloworld.md b/docs/wskdeploy_action_helloworld.md
new file mode 100644
index 0000000..2bd2c9c
--- /dev/null
+++ b/docs/wskdeploy_action_helloworld.md
@@ -0,0 +1,86 @@
+# Actions
+
+## The "Hello World" Action
+
+As with most language introductions, here we show a simple "hello world" action as encoded
in an OpenWhisk Package Manifest YAML file:
+
+### Manifest file
+
+#### _Example: “Hello world” using a NodeJS (JavaScript) action_
+```yaml
+package:
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    hello_world:
+      function: src/hello.js
+```
+
+where "hello.js" contains the following JavaScript code:
+```javascript
+function main(params) {
+    msg = "Hello, " + params.name + " from " + params.place;
+    return { greeting:  msg };
+}
+```
+
+### Deploying
+
+You can actually deploy the "hello world" manifest from the incubator-openwhisk-wskdeploy
project directory if you have downloaded it from GitHub:
+
+```sh
+$ wskdeploy -m docs/examples/manifest_hello_world.yaml
+```
+
+### Invoking
+```sh
+$ wsk action invoke hello_world_package/hello_world --blocking
+```
+
+### Result
+The invocation should return an 'ok' with a response that includes this result:
+
+```sh
+"result": {
+    "greeting": "Hello, undefined from undefined"
+},
+```
+
+The output parameter '```greeting```''s value included "_undefined_" values for the '```name```'
and '```place```' input parameters as they were not provided in the manifest.
+
+### Discussion
+
+This "hello world" example represents the minimum valid Manifest file which includes only
the required parts of the Package and Action descriptors.
+
+In the above example,
+- The Package and its Action were deployed to the user’s default namespace using the ‘package’
and 'action' names from the manifest.
+  - ```/<default namespace>/hello_world_package/hello_world```
+- The NodeJS default runtime (i.e., ```runtime: nodejs```) was selected automatically based
upon the file extension '```.js```'' of the function's source file '```hello.js```'.
+
+
+### Source code
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_hello_world.yaml](examples/manifest_hello_world.yaml)
+- [hello.js](examples/src/hello.js)
+
+### Specification
+For convenience, the Packages and Actions grammar can be found here:
+- **[Packages](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_packages.md#packages)**
+- **[Actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)**
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_package_minimal.md#packages">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <td><a href="wskdeploy_action_fixed_parms.md#actions">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_action_typed_parms.md b/docs/wskdeploy_action_typed_parms.md
new file mode 100644
index 0000000..49b6f07
--- /dev/null
+++ b/docs/wskdeploy_action_typed_parms.md
@@ -0,0 +1,84 @@
+# Actions
+
+## Typed parameters
+
+This example extends the 'Hello world' example with typed input and output Parameters.
+
+It shows how to:
+- Declare input and output parameters on the action '```hello_world```' using a simple, single-line
format.
+- Add two input parameters, '```name```' and '```place```', both of type '```string```' to
the '```hello_world```' action.
+- Add an '```integer```' parameter, '```age```', to the action.
+- Add a '```float```' parameter, '```height```', to the action.
+- Add an output parameter, '```greeting```' of type string to the '```hello_world```' action.
+
+### Manifest File
+
+#### Example 3: 'Hello world' with typed input and output parameter declarations
+```yaml
+package:
+  name: hello_world_package
+  ... # Package keys omitted for brevity
+  actions:
+    hello_world_typed_parms:
+      function: src/hello.js
+      inputs:
+        name: string
+        place: string
+        children: integer
+        height: float
+      outputs:
+greeting: string
+      outputs:
+        greeting: string
+```
+
+### Deploying
+```sh
+$ wskdeploy -m docs/examples/manifest_hello_world_typed_parms.yaml
+```
+
+### Invoking
+```sh
+$ wsk action invoke hello_world_package/hello_world_typed_parms --blocking
+```
+
+### Result
+```sh
+"result": {
+    "greeting": "Hello,  from "
+},
+```
+
+### Discussion
+
+In this example:
+
+- The default values for the '```name```' and '```place```' inputs would be set to empty
strings (i.e., \"\"), which is the default value for type '```string```', when passed to the
'hello.js' function; therefore 'greeting' will appear a follows:
+  - ```"greeting": "Hello, from "```
+- The default value for integer, zero (0), will be assigned to the 'age' parameter.
+- The default value for float, zero (0.0), will be assigned to the 'height' parameter.
+
+### Source code
+The manifest file for this example can be found here:
+- [manifest_hello_world_typed_parms.yaml](examples/manifest_hello_world_typed_parms.yaml)
+
+### Specification
+For convenience, the Actions and Parameters grammar can be found here:
+- **[Actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)**
+- **[Parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)**
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_action_fixed_parms.md#actions">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <td><a href="wskdeploy_action_advanced_parms.md#actions">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_faq.md b/docs/wskdeploy_faq.md
new file mode 100644
index 0000000..7649679
--- /dev/null
+++ b/docs/wskdeploy_faq.md
@@ -0,0 +1,11 @@
+# ```wskdeploy``` utility FAQ
+
+### What if ```wskdeploy``` finds an error in my manifest?
+
+- The ```wskdeploy``` utility will not attempt to deploy a package if an error in the manifest
is detected, but will report as much information as it can to help you locate the error in
the YAML file.
+
+### What if ```wskdeploy``` encounters an error during deployment?
+
+-  The ```wskdeploy``` utility will cease deploying as soon as it receives an error from
the target platform and display what error information it receives to you.
+- then it will attempt to undeploy any entities that it attempted to deploy.
+  - If "interactive mode" was used to deploy, then you will be prompted to confirm you wish
to undeploy.
diff --git a/docs/wskdeploy_hello_world.md b/docs/wskdeploy_hello_world.md
deleted file mode 100644
index 5994c19..0000000
--- a/docs/wskdeploy_hello_world.md
+++ /dev/null
@@ -1,77 +0,0 @@
-## Creating a "hello world" package
-
-As with most language introductions, here we show a minimal "hello world" application as
encoded in an OpenWhisk Package Manifest YAML file:
-
-### Manifest file
-```yaml
-package:
-  name: hello_world_package
-  version: 1.0
-  license: Apache-2.0
-  actions:
-    hello_world:
-      function: src/hello.js
-```
-
-where "hello.js" contains the following JavaScript code:
-```javascript
-function main(params) {
-    msg = "Hello, " + params.name + " from " + params.place;
-    return { greeting:  msg };
-}
-```
-
-### Deploying "hello world"
-
-You can actually deploy the "hello world" manifest from the incubator-openwhisk-wskdeploy
project directory if you have downloaded it from GitHub:
-
-```sh
-$ ./wskdeploy -m docs/examples/manifest_hello_world.yaml
-```
-
-### Running
-```sh
-$ wsk action invoke hello_world_package/hello_world --blocking
-```
-should return an 'ok' with a response that looks like:
-```sh
-    "response": {
-        "result": {
-            "greeting": "Hello, undefined from undefined"
-        },
-        "status": "success",
-        "success": true
-    },
-```
-
-### Discussion
-
-This "hello world" example represents the minimum valid Manifest file which includes only
the required parts of the Package and Action descriptors.
-
-- The package and action were deployed to the user’s default namespace:
-  - ```/<default namespace>/hello_world_package/hello_world```
-- The NodeJS runtime was selected automatically based upon the file extension '```.js```''
of the function's source file '```hello.js```'.
-- The parameters 'name' and 'place' in this example are not set to any default values; therefore
'greeting' will appear a follows:
-  - ```"greeting": "Hello, undefined from undefined"```
-  we will explore setting these values in later examples.
-
-### Source code
-The source code for the manifest and JavaScript files can be found here:
-- [manifest_hello_world.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml)
-- [hello.js](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/src/hello.js)
-
----
-<!--
- Bottom Navigation
--->
-<html>
-<div align="center">
-<table align="center">
-  <tr>
-    <td><a href="wskdeploy_packages.md#packages">&lt;&lt;&nbsp;previous</a></td>
-    <td><a href="programming_guide.md#guided-examples">Index</a></td>
-    <td><a href="wskdeploy_helloworld_basic_parms.md#hello-world-action-with-basic-parameters">next&nbsp;&gt;&gt;</a></td>
-  </tr>
-</table>
-</div>
-</html>
diff --git a/docs/wskdeploy_helloworld_advanced_parms.md b/docs/wskdeploy_helloworld_advanced_parms.md
deleted file mode 100644
index ac105c1..0000000
--- a/docs/wskdeploy_helloworld_advanced_parms.md
+++ /dev/null
@@ -1,64 +0,0 @@
-## Actions with advanced parameters
-
-This example builds on the previous “Hello world with basic input and output parameters”
example with more robust input and output parameter declarations by using a multi-line format
for declaration.
-
-This example:
-- shows how to declare input and output parameters on the action ‘```hello_world```’
using a multi-line grammar.
-- adds the ‘```name```’ and ‘```place```’ input parameters, both of type ‘```string```’,
to the ‘```hello_world``’ action each also includes an associated ‘```description```’
value.
-- adds the ‘```greeting```’ output parameter of explicit ‘```type```’ of ‘```string```’
to the ‘```hello_world```’ action with a ‘```description```’.
-
-### Manifest File
-
-If we want to do more than declare the type (i.e., ‘string’, ‘integer’, ‘float’,
etc.) of the input parameter, we can use the multi-line grammar.
-
-#### Example 3: input and output parameters with explicit types and descriptions
-```yaml
-package:
-  name: hello_world_package
-  ... # Package keys omitted for brevity
-  actions:
-    hello_world_3:
-      function: src/hello/hello.js
-      runtime: nodejs@6
-      inputs:
-        name:
-          type: string
-          description: name of person
-        place:
-          type: string
-          description: location of person
-      outputs:
-        greeting:
-          type: string
-          description: greeting string
-```
-
-### Discussion
-Describing the input and output parameter types, descriptions and other meta-data helps
-- tooling validate values users may input and prompt for missing values using the descriptions
provided.
-- allows verification that outputs of an Action are compatible with the expected inputs of
another Action so that they can be composed in a sequence.
-
-### Source code
-The manifest file for this example can be found here:
-- [manifest_hello_world_3.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world_2.yaml)
-
-### Specification
-For convenience, links to the schema and grammar for Actions and Parameters:
-- **Actions**: [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)
-- **Parameters** [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)
-
----
-<!--
- Bottom Navigation
--->
-<html>
-<div align="center">
-<table align="center">
-  <tr>
-    <td><a href="wskdeploy_helloworld_basic_parms.md#actions-with-basic-parameters">&lt;&lt;&nbsp;previous</a></td>
-    <td><a href="programming_guide.md#guided-examples">Index</a></td>
-    <td><a href="">next&nbsp;&gt;&gt;</a></td>
-  </tr>
-</table>
-</div>
-</html>
diff --git a/docs/wskdeploy_helloworld_basic_parms.md b/docs/wskdeploy_helloworld_basic_parms.md
deleted file mode 100644
index 21d3b82..0000000
--- a/docs/wskdeploy_helloworld_basic_parms.md
+++ /dev/null
@@ -1,59 +0,0 @@
-## Actions with basic parameters
-
-This example extends the 'Hello world' example with explicit input and output Parameter declarations.
-
-This example:
-- shows how to declare input and output parameters on the action 'hello_world'
-using a simple, single-line grammar.
-- adds two input parameters, '```name```' and '```place```', both of type '```string```'
to the '```hello_world```' action.
-- adds one output parameter, '```greeting```' of type string to the '```hello_world```' action.
-
-### Manifest File
-
-#### Example 2: 'Hello world' with explicit input and output parameter declarations
-```yaml
-package:
-  name: hello_world_package
-  ... # Package keys omitted for brevity
-  actions:
-    hello_world_2:
-      function: src/hello.js
-      inputs:
-        name: string
-        place: string
-      outputs:
-        greeting: string
-```
-
-### Discussion
-This packaging specification grammar places an emphasis on simplicity for the casual developer
who may wish to hand-code a Manifest File; however, it also provides a robust optional schema
that can be advantaged when integrating with larger application projects using design and
development tooling such as IDEs.
-
-In this example:
-
-- The default values for the '```name```' and '```place```' inputs would be set to empty
strings (i.e., ''), since they are of type 'string', when passed to the 'hello.js' function;
therefore 'greeting' will appear a follows:
-  - ```"greeting": "Hello, from "```
-
-### Source code
-The manifest file for this example can be found here:
-- [manifest_hello_world_2.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world_2.yaml)
-
-### Specification
-For convenience, links to the schema and grammar for Actions and Parameters:
-- **Actions**: [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)
-- **Parameters** [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)
-
----
-<!--
- Bottom Navigation
--->
-<html>
-<div align="center">
-<table align="center">
-  <tr>
-    <td><a href="wskdeploy_hello_world.md#creating-a-hello-world-package">&lt;&lt;&nbsp;previous</a></td>
-    <td><a href="programming_guide.md#guided-examples">Index</a></td>
-    <td><a href="wskdeploy_helloworld_advanced_parms.md#actions-with-advanced-parameters">next&nbsp;&gt;&gt;</a></td>
-  </tr>
-</table>
-</div>
-</html>
diff --git a/docs/wskdeploy_package_minimal.md b/docs/wskdeploy_package_minimal.md
new file mode 100644
index 0000000..b668595
--- /dev/null
+++ b/docs/wskdeploy_package_minimal.md
@@ -0,0 +1,97 @@
+# Packages
+
+The wskdeploy utility works primarily with the OpenWhisk **Package** resource as described
in the [OpenWhisk Packaging Specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification#openwhisk-packaging-specification).
+
+## Creating a minimal OpenWhisk Package
+
+### Start with a Package Manifest (YAML) file
+The ```wskdeploy``` utility mainly uses a single YAML file, called a "Package Manifest",
to describe all the OpenWhisk components that make up your OpenWhisk Package including Actions,
Triggers, Rules, etc.
+
+### Manifest
+
+The minimal manifest file would include only a package declaration, a version number and
a license for the package:
+```
+package:
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+```
+
+Save this into a file called ```"manifest.yaml"``` in a directory of your choice.
+
+### Deploying
+
+#### using the project path
+Simply execute the ```wskdeploy``` utility binary against the directory you saved your "manifest.yaml"
file in by pointing it to the package location using the ```-p``` flag.
+
+```sh
+$ wskdeploy -p <my_directory>
+```
+wskdeploy will automatically look for any file named ```"manifest.yaml"``` or ```"manifest.yml"```
in the directory it is pointed; however, the _manifest file can be called anything_ as long
as it has a .yaml or .yml extension and passed on the command line using the ```-m``` flag.
+
+#### using a named manifest file
+If you called your manifest "manifest_helloworld.yaml" (not using the default manifest.yaml
name) and placed it in a directory below your project directory, you could simply provide
the project-relative path to the manifest file as follows:
+```sh
+$ wskdeploy -p <my_directory> -m docs/examples/manifest_package_minimal.yaml
+```
+
+#### Interactive mode
+
+If you want to simply verify your manifest file can be read and parsed properly before deploying,
you can add the ```-i``` or ```--allow-interactive``` flag:
+
+```sh
+$ ./wskdeploy -i -m docs/examples/manifest_package_minimal.yaml
+```
+
+and the utility will stop, show you all the OpenWhisk package components it will deploy from
your manifest and ask you if you want to deploy them or not.
+
+```sh
+Package:
+Name: hello_world_package
+  bindings:
+  annotations:
+Triggers:
+Rules:
+
+Do you really want to deploy this? (y/N):
+```
+
+### Result
+You can use the Whisk CLI to confirm your package was created:
+```sh
+$ wsk package list
+
+packages
+/<default_namespace>/hello_world_package
+
+```
+
+### Discussion
+
+- The package '```hello_world_package```' was created in the user's default namespace at
their target OpenWhisk provider.
+- Currently, OpenWhisk does not yet support the '```version```' or '```license```' fields,
but are planned for future versions.  However, their values will be validated against the
specification.
+
+#### Source code
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_package_minimal.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_package_minimal.yaml)
+
+### Specification
+For convenience, the Packages grammar can be found here:
+- **[Packages](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_packages.md#packages)**
+
+---
+
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="programming_guide.md">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <td><a href="wskdeploy_action_helloworld.md#actions">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_packages.md b/docs/wskdeploy_packages.md
deleted file mode 100644
index e038711..0000000
--- a/docs/wskdeploy_packages.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Packages
-
-The wskdeploy utility works primarily with the OpenWhisk **Package** resource as described
in the [OpenWhisk Packaging Specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification#openwhisk-packaging-specification).
-
-For convenience, the schema and grammar for declaring a **Package** can be found here:
-[https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_packages.md#packages](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_packages.md#packages)
-
-## Creating an OpenWhisk Package
-
-### Start with a Package Manifest (YAML) file
-The wskdeploy utility mainly uses a single file, that uses a YAML syntax, called a "Package
Manifest", to describe all the OpenWhisk components that make up your OpenWhisk Package including
Actions, Triggers, Rules, etc.
-
-The minimal manifest file would include only a package declaration, a version number and
a license for the package:
-```
-package:
-  name: hello_world_package
-  version: 1.0
-  license: Apache-2.0
-```
-
-Save this into a file called ```"manifest.yaml"``` in a directory of your choice.
-
-### Executing the wskdeploy utility
-Simply execute the wskdeploy binary against the directory you saved your "manifest.yaml"
file in by pointing it to the package location using the ```-p``` flag.
-
-```sh
-$ wskdeploy -p <my_directory>
-```
-wskdeploy will automatically look for any file named ```"manifest.yaml"``` or ```"manifest.yml"```
in the directory it is pointed; however, the _manifest file can be called anything_ as long
as it has a .yaml or .yml extension and passed on the command line using the ```-m``` flag.
-
-For example, if you called your manifest "my_pkg_manifest.yml" you could simply provide the
manifest file name as follows:
-```sh
-$ wskdeploy -p <my_directory> -m my_pkg_manifest.yaml
-```
-### Interactive mode
-
-if you want to simply verify your manifest is able to read and parse your manifest file,
you can add the ```-i``` or ```--allow-interactive``` flag:
-
-```sh
-$ ./wskdeploy -i -m docs/examples/manifest_hello_world.yaml
-```
-
-and the utility will stop, show you all the OpenWhisk package components it will deploy and
ask you if you want to deploy them or not.
-
-```sh
-Package:
-  name: hello_world_package
-  bindings:
-
-  * action: hello_world
-    bindings:
-    annotations:
-
-  Triggers:
-  Rules:
-
-Do you really want to deploy this? (y/N):
-```
-
-Now you can verify what the utility intends to deploy and decide whether to continue onto
actual deployment with your chosen provider.
-
-#### Source code
-The source code for the manifest and JavaScript files can be found here:
-- [manifest_package_minimal.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_package_minimal.yaml)
-
-## Common questions
-
-### What if ```wskdeploy``` finds an error in my manifest?
-
-- The ```wskdeploy``` utility will not attempt to deploy a package if an error in the manifest
is detected, but will report as much information as it can to help you locate the error in
the YAML file.
-
-### What if ```wskdeploy``` encounters an error during deployment?
-
--  The ```wskdeploy``` utility will cease deploying as soon as it receives an error from
the target platform and display what error information it receives to you.
-- then it will attempt to undeploy any entities that it attempted to deploy.
-  - If "interactive mode" was used to deploy, then you will be prompted to confirm you wish
to undeploy.
-
----
-
-When ready, you can navigate to the next example _'Creating a "hello world" package'_.
-<!--
- Bottom Navigation
--->
-<html>
-<div align="center">
-<table align="center">
-  <tr>
-    <td><a href="programming_guide.md#guided-examples">&lt;&lt;&nbsp;previous</a></td>
-    <td><a href="programming_guide.md#guided-examples">Index</a></td>
-    <td><a href="wskdeploy_hello_world.md#creating-a-hello-world-package">next&nbsp;&gt;&gt;</a></td>
-  </tr>
-</table>
-</div>
-</html>
diff --git a/docs/wskdeploy_triggerrule_basic.md b/docs/wskdeploy_triggerrule_basic.md
new file mode 100644
index 0000000..68fbe63
--- /dev/null
+++ b/docs/wskdeploy_triggerrule_basic.md
@@ -0,0 +1,59 @@
+# Triggers and Rules
+
+## Adding fixed input parameters
+TODO
+
+### Manifest File
+
+#### _Example: “Hello world” with fixed input values for ‘name’ and ‘place’_
+```yaml
+package:
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+
+```
+
+### Deploying
+```sh
+$ wskdeploy -m
+```
+
+### Invoking
+```sh
+$ wsk action invoke
+```
+
+### Result
+```sh
+"result": {
+
+},
+```
+
+### Discussion
+TODO
+
+### Source code
+TODO
+
+### Specification
+For convenience, the Actions and Parameters grammar can be found here:
+- **[Triggers and Rules](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_trigger_rule.md#triggers-and-rules)**
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_action_advanced_parms.md#actions">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+<!--    <td><a href="">next&nbsp;&gt;&gt;</a></td>
-->
+  </tr>
+</table>
+</div>
+</html>

-- 
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <commits@openwhisk.apache.org>'].

Mime
View raw message