Merge pull request #69 from rajitha1998/generatorMD

An extra ReadMe file to explain the code generator

Author: rajikaimal

assets/generator/high_level_diagrams/aws_diagram.png

@@ -0,0 +1,101 @@
+# Code Generation Tool 
+
+![ts](https://flat.badgen.net/badge/Built%20With/TypeScript/blue)
+
+[![Gitter](https://img.shields.io/badge/chat-on%20gitter-brightgreen)](https://gitter.im/cloudlibz/cloudlibz)
+[![Read on : Medium](https://img.shields.io/badge/Read%20on-Medium-black.svg)](https://medium.com/leopards-lab)
+[![Mailing list : Scorelab](https://img.shields.io/badge/Mailing%20list-Scorelab-blue.svg)](https://groups.google.com/g/score-community)
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-ff69b4.svg?style=flat)](https://github.com/leopardslab/nodecloud/issues)
+
+## Code Generation in NodeCloud 
+
+This is where new source code is generated by assembling bits and pieces. The aim of this generator is to fill the JavaScript clases in NodeCloud plugins. This code generation process is based on TypeScript compiler API. This procress can be mainly divided into three main parts, 
+
+1. Parsing the type definition files of cloud SDKs
+2. Traversing through the **Abstract Syntax Tree** of the source code and collecting required data
+3. Transforming a dummy **Abstract Syntax Tree** with the collected data to generate a new source code
+
+A high level idea of the code generator can be taken from the below rich picture.
+
+![Rich picture](https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/code_generation_tool.png)
+
+The execution of the generator starts form the `main.ts` file, where the basic information regarding the service classes are taken from the `node-cloud.yml` file and depending on the cloud provider the  basic information is directed to the respective generator(e.g. - Azure generator).
+
+## Structure of `node-cloud.yml` file
+
+* AWS
+
+``` 
+AWS:
+    create: elasticbeanstalk.d.ts createApplication
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/aws.JPG" />
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/aws_diagram.png" />
+</p>
+
+* Azure
+
+``` 
+Azure:
+    create: arm-containerservice managedClusters.d.ts createOrUpdate
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/azure.jpeg" />
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/azure_diagram.jpeg" />
+</p>
+
+* Google Cloud (client based)
+
+``` 
+GCP:
+   create: container v1 cluster_manager_client.d.ts createCluster
+```
+
+``` 
+ GCP:
+    getMetricData: monitoring v3 metric_service_client.d.ts getMetricDescriptor
+    projectPath: monitoring v3 alert_policy_service_client.d.ts projectPath
+```
+
+`projectPath` is not an API request. Generator is capable of creating functions which gives relevant objects as well.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/gcp_client_based.jpeg" />
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/gcp_client_based_diagram.jpeg" />
+</p>
+
+* Google Cloud (class based)
+
+``` 
+GCP:
+   mainClass: DNS
+   createZone: dns zone.d.ts create
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/gcp_class_based.jpeg" />
+  <img src="https://raw.githubusercontent.com/rajitha1998/waterme-Project/master/gcp_class_based_diagram.jpeg" />
+</p>
+
+For the class-based SDKs there is a minor change in the `node-cloud.yml` to record the main class of an SDK. For the above scenario, it’s the DNS class.
+
+## Code parsers
+
+This is the simplest part of the code generation tool. The SDK files are read from the relevant SDKs as specified in the `node-cloud.yml` file. Afterwards, it is converted to an **Abstract Syntax Tree**. Finally, the class declaration Node of that **Abstract Syntax Tree** is returned. This retured Node is another **Abstract Syntax Tree** since a class declaration itself is another **Abstract Syntax Tree**.
+
+## Data extraction functions
+
+These functions are located in the generators of the each cloud providers. Each data extration function has a unique logic depending on the **Abstract Syntax Tree** of a SDK class. The goal here is to extract all the data required to generate the new JavaScript class. At the end it is retured as `classData`. The data extration function collects imports, clients, method parameters, types of parameters, method return types and package names. Additionally, class relationships are identified in the Google Cloud data extraction function for the Google Cloud class based transformer.
+
+## Transformers
+
+This is the most important part of the code generator tool. Currently, there are four transformers. Two transformers for Google Cloud, and one each for AWS and Azure. All of the transformers runs three main transformations. 
+
+* `addFunctions`:  In this transformation the basic structure of the code is created. Method Nodes are created to the number of functions in the `classData` object. If there are imports related to the class those statments are also added to the dummy **Abstract Syntax Tree**.
+
+* `addIdentifiers`: In this transformation all the Identifier nodes are updated. After this transformation the code is logically compelete. All the neccessary code parts are added and finalized such as parameter names, parameter types, client names, class name, package names, SDK function names etc.
+
+* `addComments`: This transformation aims to auto-generate the API documentation. All the comments are added to the structure required by `JSDoc`. The `@category` is used to categorize the generated classes depending on the cloud provider. This tag is from the `better-docs` template used with `JSDoc`.