Documentation cleanup, post-gogradle build changes (#1120)

* Documentation cleanup, post-gogradle build changes

* Documentation cleanup, post-gogradle build changes

* Documentation cleanup, post-gogradle build changes

* Documentation cleanup, post-gogradle build changes

* Update cross compile instructions for gradfle tasks

Author: mrutkows

README.md

@@ -154,29 +154,57 @@ After compiling, a suitable wskdeploy binary that works for your OS platform wil
 
 1. Verify your installed Gradle version is `5.5.1` (or higher)
 
-    - If you use Windows OS, type ```gradlew.bat -version ```.
-    - For Unix/Linux/Mac, please type ```./gradlew -version```.
+    - On Windows OS, type ```gradlew.bat -version ```.
+    - On Unix/Linux/Mac, please type ```./gradlew -version```.
 
     > **Note** Gradle v6 is not yet supported.
 
-1. For Windows type ```gradlew.bat distDocker```. For Linux/Unix/Mac, please type ```./gradlew distDocker```. These
-commands will start the wskdeploy cross compile for your specific OS platform inside a Docker container.
+1. Cross-compile binaries for all supported Operating Systems and Architectures:
 
-1. After build success, you should find a correct binary under current /bin dir of you openwhisk-deploy clone dir.
+    - On Windows, type ```gradlew.bat goBuild```
+    - On Linux/Unix/Mac, please type ```./gradlew goBuild```.
 
-If you would like to build the binaries available for all the operating systems and architectures, run the following command:
+1. Upon a successful build, all binaries can be found within the `./build` directory of your project:
 
-```sh
-$ ./gradlew distDocker -PcrossCompileWSKDEPLOY=true
-```
+    ```sh
+    $ ls build
+    darwin-amd64  linux-amd64   linux-arm64   linux-s390x   windows-amd64
+    linux-386     linux-arm     linux-ppc64le windows-386
+    ```
 
-Then, you will find the binaries and their compressed packages generated under the folder ```bin/<os>/<arch>/``` for each supported Operating System and CPU Architecture pair.
+#### Compiling for a single OS/ARCH
+
+1. View gradle build tasks for supported Operating Systems and Architectures:
+
+    ```sh
+    ./gradlew tasks
+    ```
 
-### Building for Internationalization
+    you will see build tasks for supported OS/ARCH combinations:
+
+    ```sh
+    Gogradle tasks
+    --------------
+    buildDarwinAmd64 - Custom go task.
+    buildLinux386 - Custom go task.
+    buildLinuxAmd64 - Custom go task.
+    buildLinuxArm - Custom go task.
+    buildLinuxArm64 - Custom go task.
+    buildLinuxPpc64le - Custom go task.
+    buildLinuxS390x - Custom go task.
+    buildWindows386 - Custom go task.
+    buildWindowsAmd64 - Custom go task.
+    ```
+
+    > Note: The `buildWindows386` option is only supported on Golang versions less than 1.15.
+
+#### Building for Internationalization
 
 Please follow this process for building any changes to translatable strings:
 - [How to generate the file i18n_resources.go for internationalization](https://github.com/apache/openwhisk-wskdeploy/blob/master/wski18n/README.md)
 
+---
+
 ### Running as a Go program
 
 Since ```wskdeploy``` is a GoLang program, you may choose to run it using the Go utility. After building the wskdeploy binary, you can run it as follows:

build.gradle

@@ -38,7 +38,7 @@ golang {
 }
 
 // The `gogradle` plugin was designed to work with `govendor` and `godeps` tools
-// We must disable its tasks that attempt to "fetch" dpendendencies
+// We must disable its tasks that attempt to "fetch" dependencies
 // into a "/vendor" directory and use them to build the project (which will fail)
 installDependencies.enabled = false
 resolveBuildDependencies.enabled = false

parsers/manifest_parser_test.go

@@ -1924,9 +1924,9 @@ func TestParseYAML_param(t *testing.T) {
 					assert.Equal(t, false, param.Value, "Get param value failed.")
 				case "inline0":
 					assert.Equal(t, 456.423, param.Value, "Get param value failed.")
-				case "inlin10":
+				case "inline10":
 					assert.Equal(t, nil, param.Value, "Get param value failed.")
-				case "inlin11":
+				case "inline11":
 					assert.Equal(t, true, param.Value, "Get param value failed.")
 				case "expand1":
 					assert.Equal(t, nil, param.Value, "Get param value failed.")

specification/html/spec_actions.md

@@ -20,6 +20,7 @@
 ## Actions
 
 #### Subsections
+
 - [Fields](#fields)
 - [Requirements](#requirements)
 - [Notes](#notes)
@@ -32,6 +33,7 @@
 The Action entity schema contains the necessary information to deploy an OpenWhisk function and define its deployment configurations, inputs and outputs.
 
 ### Fields
+
 | Key Name | Required | Value Type | Default | Description |
 |:---|:---|:---|:---|:---|
 | version | no | [version](spec_parameter_types.md#openwhisk-types) | N/A | The optional user-controlled version for the Action. |
@@ -78,6 +80,7 @@ The following annotations have special meanings for Actions:
 - When the `code` key-value is specified, the `runtime` **SHALL** be a required field.
 
 #### Annotation requirements
+
 - The annotation `require-whisk-auth` **SHALL** only be valid for web actions (i.e., if the `web` key or `web-export` annotation is set to `true`).
 - If the value of the `require-whisk-auth` annotation is an `integer` its value **MUST** be a positive integer less than or equal to the `MAX_INT` value of `9007199254740991`.
 - When the `web` or `web-export` key is present and set to `true` the web action's **MUST** also be marked `final`.  This happens automatically when the `web` or `web-export` keys are present and set to `true`.
@@ -175,12 +178,12 @@ See the file [runtimes.json](https://github.com/apache/openwhisk/blob/master/ans
 the main [apache/openwhisk](https://github.com/apache/openwhisk) repository for the latest supported runtimes nad versions.
 
 #### Notes
+
 - **WARNING**: _For OpenWhisk project builds, the Docker image used is tagged `nightly` in Docker Hub (e.g, for GitHub pull
 requests). Production uses of OpenWhisk code may use different images and tagged (released) image versions._
 - If no value for `runtime` is supplied, the value `language:default` will be assumed.
 - OpenWhisk runtimes may also include additional built-in packages (or libraries) that have been determined be useful for Actions surveyed and tested by the OpenWhisk platform.
 
-
 ### Recognized File extensions
 
 Although it is best practice to provide a runtime value when declaring an Action, it is not required. In those cases, that a runtime is not provided, the package tooling will attempt to derive the correct runtime based upon the the file extension for the Action's function (source code file). The

specification/html/spec_apis.md

@@ -22,6 +22,7 @@
 The API entity schema is used to define an OpenWhisk API within a manifest.
 
 ### Fields
+
 <html>
 <table width="100%">
  <tr>

specification/html/spec_entity_naming_and_namespacing.md

@@ -26,33 +26,35 @@ packages, belongs in a *namespace.*
 
 The fully qualified name of any entity has the format:
 
-```
+```sh
 /<namespaceName>[/<packageName>]/<entityName>
 ```
 
 The namespace is typically provided at bind-time by the user deploying the package to their chosen OpenWhisk platform provider.
 
 #### Requirements
 
--   The “/whisk.system“ namespace is reserved for entities that are distributed with the OpenWhisk system.
+- The “/whisk.system“ namespace is reserved for entities that are distributed with the OpenWhisk system.
 
 ### Entity Names
 
 The names of all entities, including actions, triggers, rules, packages,
 and namespaces, are a sequence of characters that follow the following
 format:
 
--   The first character SHALL be an alphanumeric character, a digit, or an underscore.
--   The subsequent characters MAY be alphanumeric, digits, spaces, or any of the following:
-```
-_, @, ., -
-```
+- The first character SHALL be an alphanumeric character, a digit, or an underscore.
+- The subsequent characters MAY be alphanumeric, digits, spaces, or any of the following:
+
+    ```sh
+    _, @, ., -
+    ```
+
 - The last character SHALL NOT be a space.
 - The maximum name length of any entity name is 256 characters (i.e., ENTITY_NAME_MAX_LENGTH = 256).
 
 Valid entity names are described with the following regular expression (Java metacharacter syntax):
 
-```
+```sh
 "\A([\w]|[\w][\w@ .-]{0,${ENTITY_NAME_MAX_LENGTH - 2}}[\w@.-])\z"
 ```
 

specification/html/spec_intro.md

@@ -31,15 +31,15 @@ Development Kits (SDKs).
 The code for the Actions, along with any support services implementing *Feeds*, are packaged according to this specification to be compatible with the OpenWhisk catalog and its tooling. It also serves as a means for architects and developers to model OpenWhisk package Actions as part
 of full, event-driven services and applications providing the necessary information for artifact and data type validation along with package management operations.
 
-### Compatibility
+## Compatibility
 
 This specification is intended to be compatible with the following specifications:
 
--   *OpenWhisk API which is defined as an OpenAPI document: *
-    -   <https://github.com/apache/openwhisk/blob/master/core/controller/src/main/resources/apiv1swagger.json>
+- *OpenWhisk API which is defined as an OpenAPI document:*
+    - <https://github.com/apache/openwhisk/blob/master/core/controller/src/main/resources/apiv1swagger.json>
 
--   *OpenAPI Specification when defining REST APIs and parameters:*
-    -   <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>
+- *OpenAPI Specification when defining REST APIs and parameters:*
+    - <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>
 
 <!--
  Bottom Navigation

specification/html/spec_maps.md

@@ -29,6 +29,7 @@ entities.
 ```
 
 ##### Multi-line grammar
+
 ```yaml
 # Where ‘key_n’ is a type <string> and ‘value_n’ is type <any>.
 <key_1>: <value_1>

specification/html/spec_normative_refs.md

@@ -17,50 +17,45 @@
 #
 -->
 
-
 <!--
 ********************************
   Normative Reference
 ********************************
 -->
 <h2>Normative References</h2>
-<p>&nbsp;</p>
+
 <table width="100%">
  <tr>
-  <th>
-  <p>Tag</p>
-  </th>
-  <th>
-  <p>Description</p>
-  </th>
+  <th>Tag</th>
+  <th>Description</th>
  </tr>
  <tr>
   <td>
-  <p><a>RFC2119</a></p>
+  <p>RFC2119</p>
   </td>
   <td>
   <p>S. Bradner, <i>Key words for use in RFCs to Indicate Requirement Levels</i>, <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>, IETF RFC 2119, March 1997.</p>
   </td>
  </tr>
  <tr>
   <td>
-  <p><a>YAML-1.2</a></p>
+  <p>YAML-1.2</p>
   </td>
   <td>
   <p>YAML, Version 1.2, 3rd Edition, Patched at 2009-10-01, Oren Ben-Kiki, Clark Evans, Ingy dšt Net <a href="http://www.yaml.org/spec/1.2/spec.html">http://www.yaml.org/spec/1.2/spec.html</a></p>
   </td>
  </tr>
  <tr>
   <td>
-  <p><a>YAML-TS-1.1</a></p>
+  <p>YAML-TS-1.1</p>
   </td>
   <td>
   <p>Timestamp Language-Independent Type for YAML Version 1.1, Working Draft 2005-01-18, <a href="http://yaml.org/type/timestamp.html">http://yaml.org/type/timestamp.html</a></p>
   </td>
  </tr>
  <tr>
   <td>
-  <p><a>Maven-Version</a></p>
+  <p>Maven-Version</p>
   </td>
   <td>
   <p>The version type is defined with the <a href="https://maven.apache.org/index.html">Apache Maven project's</a> policy draft:</p>
@@ -69,7 +64,7 @@
  </tr>
  <tr>
   <td>
-  <p><a>OpenAPI-2.0</a></p>
+  <p>OpenAPI-2.0</p>
   </td>
   <td>
   <p>The OpenAPI (f.k.a. 'Swagger') specification for defining REST APIs as JSON.</p>
@@ -78,7 +73,7 @@
  </tr>
  <tr>
   <td>
-  <p><a>Linux-SPDX</a></p>
+  <p>Linux-SPDX</p>
   </td>
   <td>
   <p>Linux Foundation, SPDX License list</p>
@@ -87,7 +82,7 @@
  </tr>
  <tr>
   <td>
-  <p><a>NPM-SPDX-Syntax</a></p>
+  <p>NPM-SPDX-Syntax</p>
   </td>
   <td>
   <p>Node Package Manager (NPM) SPDX License Expression Syntax</p>
@@ -103,19 +98,15 @@
 -->
 
 <h2>Non-normative References</h2>
-<p>&nbsp;</p>
+
 <table width="100%">
  <tr>
-  <th>
-  <p>Tag</p>
-  </th>
-  <th>
-  <p>Description</p>
-  </th>
+  <th>Tag</th>
+  <th>Description</th>
  </tr>
  <tr>
   <td>
-  <p><a>OpenWhisk-API</a></p>
+  <p>OpenWhisk-API</p>
   </td>
   <td>
   <p>OpenWhisk REST API which is defined as an OpenAPI document.</p>
@@ -124,31 +115,31 @@
  </tr>
  <tr>
   <td>
-  <p><a>GNU-units</a></p>
+  <p>GNU-units</p>
   </td>
   <td>
   <p>Size-type units are based upon a subset of those defined by GNU at <a href="http://www.gnu.org/software/parted/manual/html_node/unit.html">http://www.gnu.org/software/parted/manual/html_node/unit.html</a></p>
   </td>
  </tr>
  <tr>
   <td>
-  <p><a>RFC 6838</a></p>
+  <p>RFC 6838</p>
   </td>
   <td>
   <p>Mime Type definitions in compliance with <a href="http://tools.ietf.org/html/rfc6838">RFC 6838</a>.</p>
   </td>
  </tr>
  <tr>
   <td>
-  <p><a>RFC 7231</a></p>
+  <p>RFC 7231</p>
   </td>
   <td>
   <p>HTTP 1.1. status codes are described in compliance with <a href="http://tools.ietf.org/html/rfc7231#section-6">RFC 7231</a>.</p>
   </td>
  </tr>
  <tr>
   <td>
-  <p><a>IANA-Status-Codes</a></p>
+  <p>IANA-Status-Codes</p>
   </td>
   <td>
   <p>HTTP Status codes as defined in the <a href="http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">IANA Status Code Registry</a>.</p>
@@ -159,8 +150,8 @@
   <p>JSON Schema Specification</p>
   </td>
   <td>
-  <p>The built-in parameter type 'json' references this specification.</p>
-  <p>http://json-schema.org/</p>
+  <p>The built-in parameter type 'json' references this specification:
+  <a href="http://json-schema.org/">http://json-schema.org/</a></p>
   </td>
  </tr>
 </table>

specification/html/spec_package_processing.md

@@ -22,23 +22,22 @@
 This document defines two file artifacts that are used to deploy
 Packages to a target OpenWhisk platform; these include:
 
--   ***Package Manifest file***: Contains the Package definition along
+- ***Package Manifest file***: Contains the Package definition along
     with any included Action, Trigger or Rule definitions that comprise
     the package. This file includes the schema of input and output data
     to each entity for validation purposes.
 
--   ***Deployment file*** (optional): Contains the values and bindings used
+- ***Deployment file*** (optional): Contains the values and bindings used
     configure a Package to a target OpenWhisk platform provider’s
     environment and supply input parameter values for Packages, Actions
     and Triggers. This can include Namespace bindings, security and
     policy information.
 
 #### Notes
 
--   _Deployment files are optional_. Deployment can be fully accomplished
+- _Deployment files are optional_. Deployment can be fully accomplished
     with simply a Manifest File.
 
-
 ### Conceptual Package creation and publishing
 
 The following diagram illustrates how a developer would create OpenWhisk