Doc updates (#1054)

* Doc Updates

* Updated

* Added sample links

* Updates

* PR Comments

* Minor change

Author: sarangan12

ChangeLog.md

@@ -1,4 +1,4 @@
-## 2017.10.13 - Azure ARM version 0.15.0
+## 2017.10.17 - Azure ARM version 0.15.0
 
 * Each gem include multiple api-versions (namespace example: "Azure::Compute::Mgmt::V2017_03_30").
 * Profiles are introduced:

README.md

@@ -1,4 +1,7 @@
 
+**NOTE**: With 0.15.0 version of Azure SDK, significant changes (Multiple API versions & Profiles) have been introduced.
+The details are available [here](#azure-multiple-api-versions--profiles)
+
 # Microsoft Azure SDK for Ruby - Resource Management (preview)
 [![Build Status](https://api.travis-ci.org/Azure/azure-sdk-for-ruby.svg?branch=master)](https://api.travis-ci.org/Azure/azure-sdk-for-ruby) [![Code Climate](https://codeclimate.com/github/Azure/azure-sdk-for-ruby/badges/gpa.svg)](https://codeclimate.com/github/Azure/azure-sdk-for-ruby)
 
@@ -94,6 +97,190 @@ see [Developer’s guide to auth with Azure Resource Manager API](http://aka.ms/
 After creating the service principal, you should have three pieces of information, a client id (GUID), client secret
 (string) and tenant id (GUID) or domain name (string).
 
+# Azure Multiple API versions & Profiles
+
+With 0.15.0 of Azure SDK, multiple API versions and profiles are introduced. With these changes, each individual gem
+has multiple versions of the services and several profiles. The azure_sdk rollup gem also consists of several profiles. The following section provides details on the usage of multiple API versions and profiles.
+
+## Why Multiple API versions?
+
+Versions 0.14.0 and older, would have access to the latest versions of Azure services at the time of release. Each release up to 0.14.0, would include the latest available api-version of the services. There wasn't an option to use an older api-version of the service (except for using an older version of the sdk gem). With the introduction of multiple API versions per gem, any api-version available for the service can be explicitly targeted.
+
+## What is a  Profile?
+
+A profile is a combination of different resource types with different versions from different services. Using a profile,
+will help you mix and match between various resource types.
+
+## What to use?
+* If you would like to use the latest versions of **all** the services, then the recommendation is to use the **Latest** profile of the Azure SDK rollup gem.
+
+* If you would like to use the services compatible with the **Azure Stack**, then the recommendation is to use the **V2017_03_09** profile of the Azure SDK rollup gem.
+
+* If you would like to use the **latest** api-version of a service, then the recommendation is to use the **Latest** profile of the specific gem. For example, if you would like to use the latest api-version of compute service alone, use the Latest profile of compute gem.
+
+* If you would like to use **specific** api-version of a service, then the recommendation is to use the **specific API** versions defined inside that gem.
+
+Note: All the above options could be combined within the same application.
+
+## Usage of azure_sdk gem
+
+azure_sdk gem is a rollup of all the supported gems in the Ruby SDK. This gem consists of a **Latest** profile which supports the latest version of all services. it introduces a versioned profile **V2017_03_09** profile which is built for Azure Stack.
+
+### Install
+
+You can install the azure_sdk rollup gem with the following command:
+
+```ruby
+gem install 'azure_sdk'
+```
+
+### Existing Profiles
+
+To start with, the azure_sdk rollup gem has two profiles.
+  1. V2017_03_09 (Profile built for Azure Stack)
+  2. Latest (Profile consists of Latest versions of all services)
+
+You could choose the profile that you would like to use. If you would like to use the latest versions of **all** the services, then the recommendation is to use the **Latest** profile of the azure_sdk rollup gem.
+
+If you would like to use the services compatible with the **Azure Stack**, then the recommendation is to use the **V2017_03_09** profile of the Azure SDK rollup gem. 
+
+### Usage
+
+The following lines should be used to instantiate a profile client:
+
+```ruby
+# Provide credentials
+provider = MsRestAzure::ApplicationTokenProvider.new(
+       ENV['AZURE_TENANT_ID'],
+       ENV['AZURE_CLIENT_ID'],
+       ENV['AZURE_CLIENT_SECRET'])
+credentials = MsRest::TokenCredentials.new(provider)
+
+options = {
+  credentials: credentials,
+  subscription_id: ENV['AZURE_SUBSCRIPTION_ID']
+}
+
+# Target profile built for Azure Stack
+profile_client = Azure::Profiles::V2017_03_09::Mgmt::Client.new(options)
+```
+
+The profile client could be used to access individual RPs:
+
+ ```ruby
+# To access the operations associated with Compute
+profile_client.compute.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'
+
+# Option 1: To access the models associated with Compute
+purchase_plan_obj = profile_client.compute.model_classes.purchase_plan.new
+
+# Option 2: To access the models associated with Compute
+# Notice Namespace: Azure::Profiles::<Profile Name>::<Service Name>::Mgmt::Models::<Model Name>
+purchase_plan_obj = Azure::Profiles::V2017_03_09::Compute::Mgmt::Models::PurchasePlan.new
+
+```
+
+## Usage of Individual gem using Profiles
+
+### Install
+
+You can install the individual gems using gem install. For eg, to install azure_mgmt_compute, use the following command:
+
+```ruby
+gem install 'azure_mgmt_compute'
+```
+### Usage
+
+The following lines should be used to instantiate a profile client:
+
+```ruby
+# Provide credentials
+provider = MsRestAzure::ApplicationTokenProvider.new(
+       ENV['AZURE_TENANT_ID'],
+       ENV['AZURE_CLIENT_ID'],
+       ENV['AZURE_CLIENT_SECRET'])
+credentials = MsRest::TokenCredentials.new(provider)
+
+options = {
+  credentials: credentials,
+  subscription_id: ENV['AZURE_SUBSCRIPTION_ID']
+}
+
+# Target profile built for Latest Compute
+profile_client = Azure::Compute::Profiles::Latest::Mgmt::Client.new(options)
+```
+The profile client could be used to access operations and models:
+
+ ```ruby
+# To access the operations associated with Compute
+profile_client.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'
+
+# Option 1: To access the models associated with Compute
+purchase_plan_obj = profile_client.model_classes.purchase_plan.new
+
+# Option 2: To access the models associated with Compute
+# Notice Namespace: Azure::<Service Name>::Profiles::<Profile Name>::Mgmt::Models::<Model Name>
+purchase_plan_obj = Azure::Compute::Profiles::Latest::Mgmt::Models::PurchasePlan.new
+
+```
+
+## Usage of Individual gem using using specific api-version
+
+In the previous section, we used the profile associated with individual gem. In the current section, we could use the
+version directly.
+
+### Install
+
+You can install the individual gems using gem install. For eg, to install azure_mgmt_compute, use the following command:
+
+```ruby
+gem install 'azure_mgmt_compute'
+```
+### Usage
+
+The following lines should be used to instantiate a profile client:
+
+```ruby
+# Provide credentials
+provider = MsRestAzure::ApplicationTokenProvider.new(
+       ENV['AZURE_TENANT_ID'],
+       ENV['AZURE_CLIENT_ID'],
+       ENV['AZURE_CLIENT_SECRET'])
+credentials = MsRest::TokenCredentials.new(provider)
+
+options = {
+  credentials: credentials,
+  subscription_id: ENV['AZURE_SUBSCRIPTION_ID']
+}
+
+# Target client for 2016_03_30 version of Compute
+compute_client = Azure::Compute::Mgmt::V2016_03_30::ComputeManagementClient.new(credentials)
+compute_client.subscription_id = subscription_id
+```
+
+The compute client could be used to access operations and models:
+
+ ```ruby
+# To access the operations associated with Compute
+compute_client.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'
+
+# To access the models associated with Compute
+# Notice Namespace: Azure::<Service Name>::Mgmt::<Version Name>::Models::<Model Name>
+purchase_plan_obj = Azure::Compute::Mgmt::V2016_03_30::Models::PurchasePlan.new
+
+```
+
+## Samples using Profiles
+
+The following samples could be used as a reference for Profiles usage::
+
+* [Compute MSI VM](https://github.com/Azure-Samples/compute-ruby-msi-vm)
+* [Resource Manager & Groups](https://github.com/Azure-Samples/resource-manager-ruby-resources-and-groups)
+* [Compute Manage VM](https://github.com/Azure-Samples/compute-ruby-manage-vm)
+* [Template Deployment](https://github.com/Azure-Samples/resource-manager-ruby-template-deployment)
+* [Traffic Manager Profiles](https://github.com/Azure-Samples/traffic-manager-ruby-manage-profiles)
+
+
 ### Getting Started Samples
 The tests for the libraries should provide a good example of how to get started with the clients. You can also see the
 readme for each of the libraries [Compute](management/azure_mgmt_compute),
@@ -138,7 +325,7 @@ bundle install
  example:
 ```bash
  cd ./management/azure_mgmt_compute
- rspec spec/virtual_machines_spec.rb
+ rspec spec/2017-03-30/virtual_machines_spec.rb
 ```
 **If vcr cassette exist then it'll replay the test otherwise it'll record it.**