update the services readme (#448)

Author: ctaggart

services/README.md

@@ -1,57 +1,43 @@
 # Azure Service Crates
 
-Rust crates for accessing [Azure services](https://azure.microsoft.com/services/). These crates are client libraries generated by [AutoRust](autorust) using the web service [specifications](https://github.com/Azure/azure-rest-api-specs/tree/master/specification) found in Azure/azure-rest-api-specs. The specifications are divided into two categories - [control plane and data plane](https://docs.microsoft.com/azure/azure-resource-manager/management/control-plane-and-data-plane). "You use the control plane to manage resources in your subscription. You use the data plane to use capabilities exposed by your instance of a resource type."
+Rust crates for accessing [Azure services](https://azure.microsoft.com/services/). These crates are client libraries generated by [AutoRust](autorust) using the web service [specifications](https://github.com/Azure/azure-rest-api-specs/tree/master/specification). The specifications are divided into two categories - [control plane and data plane](https://docs.microsoft.com/azure/azure-resource-manager/management/control-plane-and-data-plane). "You use the control plane to manage resources in your subscription. You use the data plane to use capabilities exposed by your instance of a resource type."
 
-There are 168 specifications. So far, we have generated 100 control plane crates. We expect that number to go up as AutoRust matures and bugs are fixed.
+When this document was last updated, there were 185 [control plane crates](mgmt) and 29 [data plane crates](svc).
 
 ## Control Plane Crates
-The control plane crates are named `azure_mgmt_${specification_directory}`, such as `azure_mgmt_storage`. Each service may have multiple API versions. Each API version has a set of OpenAPI 2.0 documents, listed under a `Tag` in a [readme.md](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md) file in a `Configuration` section. Sometimes there are multiple `Tag`s for the same API version. For example, [Tag: package-2018-07](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md#tag-package-2018-07) and [Tag: package-2018-07-only](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md#tag-package-2018-07-only). Rust code is generated for each tag and organized as a crate feature. The first tag without `-preview` is selected as the default feature:
+The control plane crates are named `azure_mgmt_${servicename}`, such as `azure_mgmt_storage`.
 
-``` toml
-[features]
-default = ["package-2019-06"]
-"package-2020-08-preview" = []
-"package-2019-06" = []
-"package-2019-04" = []
-"package-2018-11" = []
-"package-2018-07" = []
-"package-2018-07-only" = []
-"package-2018-03" = []
-"package-2018-02" = []
-"package-2017-10" = []
-"package-2017-06" = []
-"package-2016-12" = []
-"package-2016-05" = []
-"package-2016-01" = []
-"package-2015-06" = []
-"package-2015-05-preview" = []
-```
+## Data Plane Crates
+The data plane crates will be named `azure_svc_${servicename}`, such as `azure_svc_storage`.
 
-The default feature will be used when this dependency is specified:
-``` toml
-[dependencies]
-azure_mgmt_storage = { git = "https://github.com/Azure/azure-sdk-for-rust" }
+## Examples
+There are a few examples:
+- azure_mgmt_storage
+    - [storage_account_list](mgmt/storage/examples/storage_account_list.rs)
+- azure_mgmt_resources
+    - [group_create](mgmt/resources/examples/group_create.rs)
+- azure_mgmt_compute
+    - [vm_list](mgmt/compute/examples/vm_list.rs)
+- azure_mgmt_vmware
+    - [private_cloud_list](mgmt/vmware/examples/private_cloud_list.rs)
+- azure_svc_batch
+    - [list_pools](svc/batch/examples/list_pools.rs)
+
+These services are in their own [Rust workspace](Cargo.toml), so you need to change to the `services` directory to run these examples.
+``` sh
+cd azure-sdk-for-rust/services
+cargo run --package azure_mgmt_storage --example storage_account_list
 ```
 
-To use another tag, for example to try out the newer preview API, you must disable the default:
-``` toml
-[dependencies]
-azure_mgmt_storage = { git = "https://github.com/Azure/azure-sdk-for-rust", default-features = false, features = ["package-2020-08-preview"] }
-```
+## Dependencies
+These creates depend on `azure_core` and `azure_identity`. They are not yet published to [crates.io](https://crates.io/). See the [milestones](https://github.com/Azure/azure-sdk-for-rust/milestones) to see what is left before that happens. Here is an example of adding `azure_svc_batch` as a dependency.
 
-A few use cases require using more than tag. This can be done by [renaming the dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml):
 ``` toml
 [dependencies]
-azure_mgmt_storage_2019_06 = { package = "azure_mgmt_storage", git = "https://github.com/Azure/azure-sdk-for-rust", default-features = false, features = ["package-2019-06"] }
-azure_mgmt_storage_2018_02 = { package = "azure_mgmt_storage", git = "https://github.com/Azure/azure-sdk-for-rust", default-features = false, features = ["package-2018-02"] }
+tokio = { version = "1.0", features = ["macros"] }
+azure_core = { git = "https://github.com/Azure/azure-sdk-for-rust" }
+azure_identity = { git = "https://github.com/Azure/azure-sdk-for-rust" }
+azure_svc_batch = { git = "https://github.com/Azure/azure-sdk-for-rust" }
 ```
 
-## Data Plane Crates
-The data plane crates will be named `azure_svc_${specification_directory}`, such as `azure_svc_storage`.
-
-## Examples
-There are a few examples:
-- [mgmt/storage/examples/storage_account_list.rs](mgmt/storage/examples/storage_account_list.rs)
-- [mgmt/resources/examples/group_create.rs](mgmt/resources/examples/group_create.rs)
-- [mgmt/compute/examples/vm_list.rs](mgmt/compute/examples/vm_list.rs)
-- [mgmt/vmware/examples/vmware_private_cloud_list.rs](mgmt/vmware/examples/vmware_private_cloud_list.rs)
+Each crate may support several [API versions](api-versions.md).

services/api-versions.md

@@ -0,0 +1,49 @@
+# API Versions
+
+Each service may have multiple API versions. Each API version has a set of OpenAPI 2.0 documents, listed under a `Tag` in a [readme.md](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md) file in a `Configuration` section. Sometimes there are multiple `Tag`s for the same API version. For example, [Tag: package-2018-07](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md#tag-package-2018-07) and [Tag: package-2018-07-only](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md#tag-package-2018-07-only). Rust code is generated for each tag and organized as a crate feature. The first tag without `-preview` is selected as the default feature:
+
+``` toml
+[features]
+default = ["package-2019-06"]
+"package-2020-08-preview" = []
+"package-2019-06" = []
+"package-2019-04" = []
+"package-2018-11" = []
+"package-2018-07" = []
+"package-2018-07-only" = []
+"package-2018-03" = []
+"package-2018-02" = []
+"package-2017-10" = []
+"package-2017-06" = []
+"package-2016-12" = []
+"package-2016-05" = []
+"package-2016-01" = []
+"package-2015-06" = []
+"package-2015-05-preview" = []
+```
+
+The default feature will be used when this dependency is specified:
+``` toml
+[dependencies]
+azure_mgmt_storage = { git = "https://github.com/Azure/azure-sdk-for-rust" }
+```
+
+To use another tag, for example to try out the newer preview API, you must disable the default:
+``` toml
+[dependencies]
+azure_mgmt_storage = { git = "https://github.com/Azure/azure-sdk-for-rust", default-features = false, features = ["package-2020-08-preview"] }
+```
+
+A few use cases require using more than tag. This can be accomplished a couple of ways. Specify the feature `no-default-version` and the other tags you wish to use.
+
+``` toml
+[dependencies]
+azure_mgmt_storage = { git = "https://github.com/Azure/azure-sdk-for-rust", features = ["no-default-version", "package-2019-06", "package-2018-02"] }
+```
+
+Or it can be done by [renaming the dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml):
+``` toml
+[dependencies]
+azure_mgmt_storage_2019_06 = { package = "azure_mgmt_storage", git = "https://github.com/Azure/azure-sdk-for-rust", default-features = false, features = ["package-2019-06"] }
+azure_mgmt_storage_2018_02 = { package = "azure_mgmt_storage", git = "https://github.com/Azure/azure-sdk-for-rust", default-features = false, features = ["package-2018-02"] }
+```

services/mgmt/compute/examples/vm_list.rs

@@ -1,5 +1,7 @@
 /*
 Prints the name of pools using the data plane APIs
+
+cargo run --package azure_svc_batch --example list_pools
 */
 
 use azure_identity::token_credentials::AzureCliCredential;