Quickstart for Track 2 preview management libraries and update root readme for track 2

README.md

@@ -19,7 +19,8 @@ The client libraries are supported on Python 2.7 and 3.5.3 or later.
 Each service might have a number of libraries available from each of the following categories:
 * [Client - New Releases](#Client-New-Releases)
 * [Client - Previous Versions](#Client-Previous-Versions)
-* [Management](#Management)
+* [Management - New Releases](#Management-New-Releases)
+* [Management - Previous Versions](#Management-Previous-Versions)
 
 ### Client: New Releases
 
@@ -33,9 +34,15 @@ You can find the [most up to date list of all of the new packages on our page](h
 
 Last stable versions of packages that have been provided for usage with Azure and are production-ready. These libraries provide you with similar functionalities to the Preview ones as they allow you to use and consume existing resources and interact with them, for example: upload a blob. They might not implement the [guidelines](https://azure.github.io/azure-sdk/python_introduction.html) or have the same feature set as the Novemeber releases. They do however offer wider coverage of services.
 
-### Management
+### Management: New Releases
+A new set of management libraries that follow the [Azure SDK Design Guidelines for Python](https://azure.github.io/azure-sdk/python/guidelines/) are now in Public Preview. These new libraries provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. 
+You can find the list of new packages [on this page](https://azure.github.io/azure-sdk/releases/latest/python.html). Documentation and code samples for these new libraries can be found [here](https://azure.github.io/azure-sdk-for-python)
 
-Libraries which enable you to provision specific resources. They are responsible for directly mirroring and consuming Azure service's REST endpoints. The management libraries use the `azure-mgmt-<service name>` convention for their package names.
+> NOTE: If you need to ensure your code is ready for production use one of the stable, non-preview libraries.
+
+### Management: Previous Versions
+For a complete list of management libraries which enable you to provision and manage Azure resources, please check [here](https://azure.github.io/azure-sdk/releases/latest/all/python.html). They might not have the same feature set as the new releases but they do offer wider coverage of services.
+Management libraries can be identified by namespaces that start with `azure-mgmt-`, e.g. `azure-mgmt-compute`
 
 ## Need help?
 

doc/sphinx/index.rst

@@ -65,6 +65,7 @@ section of the project.
 
   installation
   quickstart_authentication
+  mgmt_preview_quickstart
   multicloud
   exceptions
   Service Management (Legacy) <servicemanagement>

doc/sphinx/mgmt_preview_quickstart.rst

@@ -0,0 +1,152 @@
+Quickstart Tutorial - Resource Management (Preview Libraries)
+===============================================================
+
+We are excited to announce that a new set of management libraries are now in Public Preview.
+Those packages share a number of new features such as Azure Identity support,
+HTTP pipeline, error-handling.,etc, and they also follow the new Azure SDK guidelines which
+create easy-to-use APIs that are idiomatic, compatible, and dependable.
+
+You can find the details of those new libraries `here <https://azure.github.io/azure-sdk/releases/latest/#python>`__
+
+In this basic quickstart guide, we will walk you through how to
+authenticate to Azure using the preview libraries and start interacting with
+Azure resources. There are several possible approaches to
+authentication. This document illustrates the most common scenario
+
+Prerequisites
+-------------
+
+| You will need the following values to authenticate to Azure
+
+- **Subscription ID**
+- **Client ID** 
+- **Client Secret** 
+- **Tenant ID** 
+
+These values can be obtained from the portal, here's the instructions:
+
+Get Subscription ID
+^^^^^^^^^^^^^^^^^^^
+
+1. Login into your Azure account
+2. Select Subscriptions in the left sidebar
+3. Select whichever subscription is needed
+4. Click on Overview
+5. Copy the Subscription ID
+
+Get Client ID / Client Secret / Tenant ID 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For information on how to get Client ID, Client Secret, and Tenant ID, please refer to `this document <https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal>`__
+
+Setting Environment Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After you obtained the values, you need to set the following values as
+your environment variables
+
+-  ``AZURE_CLIENT_ID``
+-  ``AZURE_CLIENT_SECRET``
+-  ``AZURE_TENANT_ID``
+-  ``AZURE_SUBSCRIPTION_ID``
+
+To set the following environment variables on your development system:
+
+Windows (Note: Administrator access is required)
+
+1. Open the Control Panel
+2. Click System Security, then System
+3. Click Advanced system settings on the left
+4. Inside the System Properties window, click the Environment Variables… button.
+5. Click on the property you would like to change, then click the Edit… button. If the property name is not listed, then click the New… button.
+
+Linux-based OS
+::
+
+    export AZURE_CLIENT_ID="__CLIENT_ID__"
+    export AZURE_CLIENT_SECRET="__CLIENT_SECRET__"
+    export AZURE_TENANT_ID="__TENANT_ID__"
+    export AZURE_SUBSCRIPTION_ID="__SUBSCRIPTION_ID__"
+
+Authentication and Creating Resource Management Client
+------------------------------------------------------
+
+Now that the environment is setup, all you need to do is to create an
+authenticated client. Our default option is to use
+**DefaultAzureCredential** and in this guide we have picked
+**Resources** as our target service, but you can set it up similarly for any other service that you are using.
+
+To authenticate to Azure and create
+a management client, simply do the following:
+
+::
+
+    import azure.mgmt.resource
+    import azure.mgmt.network
+    import azure.mgmt.compute
+    from azure.identity import DefaultAzureCredential
+    ...
+    subscription_id = os.environ.get("AZURE_SUBSCRIPTION_ID")
+    credential = DefaultAzureCredential()
+    resource_client = azure.mgmt.resource.ResourceManagementClient(credential=credential, subscription_id=subscription_id)
+
+More information and different authentication approaches using Azure Identity can be found in
+`this document <https://docs.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python>`__
+
+Managing Resources
+------------------
+
+Now that we are authenticated, we can use our management client to make API
+calls. Let's create a resource group and demonstrate management client's usage
+
+**Create a resource group**
+
+::
+
+    location = "mylocation"
+    group_name = "my_resource_group_name"
+    group = resource_client.resource_groups.create_or_update(
+        group_name,
+        {'location': location}
+    )
+
+**Update a resource group**
+
+::
+
+    group_name = "my_resource_group_name"
+    group.tags = {
+        "environment":"test",
+        "department":"tech"
+    }
+    updated_group = resource_client.resource_groups.create_or_update(group_name, group)
+
+**List all resource groups**
+
+::
+
+    group_list = self.resource_client.resource_groups.list()
+    for g in group_list:
+        print_resource_group(g)
+
+**Delete a resource group**
+
+::
+
+    delete_async_op = resource_client.resource_groups.begin_delete(group_name)
+    delete_async_op.wait()
+
+Need help?
+----------
+- File an issue via `Github Issues <https://github.com/Azure/azure-sdk-for-python/issues>`__ and make sure you add the "Preview" label to the issue
+- Check `previous questions <https://stackoverflow.com/questions/tagged/azure+python>`__ or ask new ones on StackOverflow using azure and python tags.
+
+Contributing
+------------
+For details on contributing to this repository, see the contributing guide.
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
+
+This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.