update docs (#639)

Co-authored-by: bmc-msft <[email protected]>

Author: cataggar

FAQ.md

@@ -1,8 +1,8 @@
 # Frequently Asked Questions
 
-## When will the crates be published to crates.io?
+## Why is it unofficial?
 
-We want them to be published soon too! [Milestones](https://github.com/Azure/azure-sdk-for-rust/milestones) have been created to help figure out issues remaining.
+This is an *unofficial* Azure SDK because it is not yet supported by Azure Support or the Azure SDK team. It has been built primarily by volunteers on their own time. For more information, see the [project history](HISTORY.md).
 
 ## How do we build a case for making it official?
 

HISTORY.md

@@ -24,8 +24,14 @@ They were last published in September of 2020 before moving the code to https://
 The above crates have become:
 - azure_core
 - azure_identity
-- azure_cosmos
+- azure_data_cosmos
 - azure_storage
+- azure_storage
+- azure_storage_blobs
+- azure_data_tables
+- azure_storage_queues
+
+They were first published in January of 2022.
 
 ## azure-sdk-keyvault
 

README.md

@@ -1,33 +1,31 @@
-# \[Unofficial\] Azure SDK for Rust
+# Azure SDK for Rust
 
-This repository is for the development of the *unofficial* Azure SDK for Rust. It is *unofficial* because it is not yet supported by Azure Support or the Azure SDK team. It has been built primarily by volunteers on their own time. For more information, see the [project history](HISTORY.md) or [FAQs](FAQ.md):
-- When will the crates be published to crates.io?
-- How do we build a case for making it official?
+This repository is for the development of the [unofficial](https://github.com/Azure/azure-sdk-for-rust/blob/main/FAQ.md#why-is-it-unofficial) Azure SDK for Rust.
 
 ## Crates
 
+[All Azure SDK for Rust crates](https://crates.io/teams/github:azure:azure-sdk-publish-rust) are published on crates.io.
+
 ### SDK
-These crates are available from in (sdk):
-- azure_core
-- azure_identity
-- azure_data_cosmos
-- azure_data_tables
-- azure_iot_hub
-- azure_security_keyvault
-- azure_storage_blobs
-- azure_storage_datalake
-- azure_storage_queues
+These [SDK crates](sdk) are available:
+- [azure_core](https://crates.io/crates/azure_core)
+- [azure_identity](https://crates.io/crates/azure_identity)
+- [azure_data_cosmos](https://crates.io/crates/azure_data_cosmos)
+- [azure_data_tables](https://crates.io/crates/azure_data_tables)
+- [azure_iot_hub](https://crates.io/crates/azure_iot_hub)
+- [azure_security_keyvault](https://crates.io/crates/azure_security_keyvault)
+- [azure_storage_blobs](https://crates.io/crates/azure_storage_blobs)
+- [azure_storage_datalake](https://crates.io/crates/azure_storage_datalake)
+- [azure_storage_queues](https://crates.io/crates/azure_storage_queues)
 
 ### Services
-More than 200 Azure service crates are available in [services](services). They are generated from the [Azure REST API Specifications](https://github.com/Azure/azure-rest-api-specs).
+Azure service crates generated from [Azure REST API Specifications](https://github.com/Azure/azure-rest-api-specs) are available in [services](services).
 
 ## Status
 
-🚨🚨🚨**WARNING**: This project is currently under very active development.🚨🚨🚨
-
-This projects' crates have yet to released to crates.io so in order to use them you will need to specify them as git dependencies. You should be aware that large, breaking changes can happen at any time, and thus it's not yet recommended to use these crates in any serious capacity yet.
+🚨 WARNING 🚨: This project is under active development. Be aware that large breaking changes will happen before 1.0 is reached.
 
-Additionally, this project is the logical successor to the previous Azure SDK crates found under [github.com/MindFlavor/AzureSDKForRust](https://github.com/MindFlavor/AzureSDKForRust). The crates have been renamed, so those older crates should be considered fully deprecated.
+This project is the successor to the `azure_sdk*` crates from [MindFlavor/AzureSDKForRust](https://github.com/MindFlavor/AzureSDKForRust). The crates have been renamed, so those older crates should be considered fully deprecated. See [history](HISTORY.md) for more details.
 
 ## Project Structure
 

_config.yml

@@ -2,7 +2,7 @@
 
 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."
 
-When this document was last updated, there were 185 [control plane crates](mgmt) and 29 [data plane crates](svc).
+When this document was last updated, there were 202 [control plane crates](mgmt) with 1437 [tags](api-versions.md) and 38 [data plane crates](svc) with 139 [tags](api-versions.md).
 
 ## Control Plane Crates
 The control plane crates are named `azure_mgmt_${servicename}`, such as `azure_mgmt_storage`.
@@ -39,5 +39,3 @@ azure_core = "0.1"
 azure_identity = "0.1"
 azure_svc_batch = "0.1"
 ```
-
-Each crate may support several [API versions](api-versions.md).

services/README.md

@@ -1,7 +1,12 @@
 # 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:
+A `Configuration` section `Tag` in a `readme.md` represents a set of operations for an Azure service for generating a client SDK. Ideally, there is a single tag representing an API version for a service.
 
+Unfortunately, some services use [multiple API versions](https://github.com/Azure/azure-sdk-for-rust/issues/563) in their tags. In this case, different service operations will use different API versions of the same service.
+
+Using the `azure_mgmt_storage` crate as an example. It is generated from the [specification/storage/resource-manager/readme.md](https://github.com/Azure/azure-rest-api-specs/blob/master/specification/storage/resource-manager/readme.md). In its [Cargo.toml](https://github.com/Azure/azure-sdk-for-rust/blob/main/services/mgmt/storage/Cargo.toml), you can see the list of `features`. A crate feature is generated for each tag. The first tag without `-preview` is selected as the default. In its [lib.rs](https://github.com/Azure/azure-sdk-for-rust/blob/main/services/mgmt/storage/src/lib.rs), you can see that a module is generated for each tag as well.
+
+Here is an example `Cargo.toml`.
 ``` toml
 [features]
 default = ["package-2019-06"]
@@ -12,38 +17,30 @@ default = ["package-2019-06"]
 "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:
+The default tag will be used when this dependency is specified as:
 ``` toml
 [dependencies]
-azure_mgmt_storage = { git = "https://github.com/Azure/azure-sdk-for-rust" }
+azure_mgmt_storage = "0.1"
 ```
 
 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"] }
+azure_mgmt_storage = { version = "0.1", 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"] }
+azure_mgmt_storage = { version = "0.1", 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"] }
+azure_mgmt_storage_2019_06 = { package = "azure_mgmt_storage", version = "0.1", default-features = false, features = ["package-2019-06"] }
+azure_mgmt_storage_2018_02 = { package = "azure_mgmt_storage", version = "0.1", default-features = false, features = ["package-2018-02"] }
 ```

services/api-versions.md

@@ -5,14 +5,17 @@ use autorust_codegen::get_mgmt_readmes;
 pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
 
 fn main() -> Result<()> {
+    let mut tag_count = 0;
     for (i, spec) in get_mgmt_readmes()?.iter().enumerate() {
         println!("{} {}", i + 1, spec.spec());
         for config in spec.configs()? {
             println!("  {}", &config.tag);
             for input_file in &config.input_files {
                 println!("    {}", input_file);
             }
+            tag_count += 1;
         }
     }
+    println!("{} tags", tag_count);
     Ok(())
 }

services/autorust/codegen/examples/mgmt_tags.rs

@@ -5,14 +5,17 @@ use autorust_codegen::{self, get_svc_readmes};
 pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
 
 fn main() -> Result<()> {
+    let mut tag_count = 0;
     for (i, spec) in get_svc_readmes()?.iter().enumerate() {
         println!("{} {}", i + 1, spec.spec());
         for config in spec.configs()? {
             println!("  {}", &config.tag);
             for input_file in &config.input_files {
                 println!("    {}", input_file);
             }
+            tag_count += 1;
         }
     }
+    println!("{} tags", tag_count);
     Ok(())
 }