Update track 1 READMEs with notice (#1841)

* Update track 1 READMEs with notice * Regenerate mgmt, svc crates Also fixes a couple azure_svc_storage examples that somehow didn't cause errors previously. * Import READMEs and remove cargo-readme Fixes style check by removing use of `cargo-readme`. Instead, we'll just import the READMEs as we recommend in our modern guidelines.
Azure · Oct 9, 2024 · 25ebe5a · 25ebe5a
1 parent faa662c
commit 25ebe5a
Show file tree

Hide file tree

Showing 335 changed files with 2,246 additions and 376 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,13 @@
 
 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.
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 ## Crates
 
 [All Azure SDK for Rust crates](https://crates.io/teams/github:azure:azure-sdk-publish-rust) are published on crates.io.

diff --git a/eng/scripts/cargo_readme.sh b/eng/scripts/cargo_readme.sh
diff --git a/eng/scripts/code_style.sh b/eng/scripts/code_style.sh
@@ -10,12 +10,7 @@ export RUSTFLAGS="-Dwarnings"
 
 rustup update --no-self-update ${BUILD}
 rustup component add rustfmt --toolchain ${BUILD}
-cargo +${BUILD} install cargo-readme
 cargo +${BUILD} fmt --all -- --check
 cargo +${BUILD} clippy --all
 cargo +${BUILD} doc --all --no-deps
 ./eng/scripts/check_json_format.sh
-./eng/scripts/cargo_readme.sh
-if git status sdk | grep -q '.md$'; then
-    echo "Run ./eng/scripts/cargo_readme.sh to update readmes" && exit 1
-fi
diff --git a/sdk/core/README.md b/sdk/core/README.md
@@ -1,5 +1,12 @@
 # azure_core
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 Core types and traits for the Rust Azure SDK.
 
 This crate is part of the unofficial Azure SDK effort in Rust. For more

diff --git a/sdk/core/src/lib.rs b/sdk/core/src/lib.rs
@@ -1,13 +1,4 @@
-//! Core types and traits for the Rust Azure SDK.
-//!
-//! This crate is part of the unofficial Azure SDK effort in Rust. For more
-//! information on the project and an overview of other crates, please refer to
-//! [our GitHub repository](https://github.com/azure/azure-sdk-for-rust).
-//!
-//! It is a library that provides cross-cutting services to other client
-//! libraries.  Please see the [general
-//! guidelines](https://azure.github.io/azure-sdk/general_azurecore.html).
-
+#![doc = include_str!("../README.md")]
 #![forbid(unsafe_code)]
 #![deny(missing_debug_implementations, nonstandard_style)]
 // #![warn(missing_docs, future_incompatible, unreachable_pub)]

diff --git a/sdk/data_cosmos/README.md b/sdk/data_cosmos/README.md
@@ -1,5 +1,12 @@
 # azure_data_cosmos
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 ## The Cosmos DB crate.
 
 `azure-data-cosmos` offers functionality needed to interact with Cosmos DB from Rust. As an abstraction over the [Cosmos DB
@@ -8,7 +15,7 @@ should also be possible with this crate.
 
 ### Examples
 
-```rust
+```rust no_run
 // Using the prelude module of the Cosmos crate makes easier to use the Rust Azure SDK for Cosmos DB.
 use azure_data_cosmos::prelude::*;
 use azure_core::Context;

diff --git a/sdk/data_cosmos/src/lib.rs b/sdk/data_cosmos/src/lib.rs
@@ -1,88 +1,7 @@
+#![doc = include_str!("../README.md")]
 #![allow(clippy::enum_variant_names)]
 #![allow(clippy::new_without_default)]
 #![allow(clippy::module_inception)]
-
-/*!
-# The Cosmos DB crate.
-
-`azure-data-cosmos` offers functionality needed to interact with Cosmos DB from Rust. As an abstraction over the [Cosmos DB
-Rest API](https://docs.microsoft.com/rest/api/cosmos-db/), anything that is possible through that Rest API
-should also be possible with this crate.
-
-## Examples
-
-```no_run
-// Using the prelude module of the Cosmos crate makes easier to use the Rust Azure SDK for Cosmos DB.
-use azure_data_cosmos::prelude::*;
-use azure_core::Context;
-use serde::{Deserialize, Serialize};
-
-// This is the stuct we want to use in our sample.
-// Make sure to have a collection with partition key "number" for this example to
-// work (you can create with this SDK too, check the examples folder for that task).
-#[derive(Serialize, Deserialize, Debug)]
-struct MySampleStruct {
-    id: String,
-    string: String,
-    number: u64,
-}
-
-impl azure_data_cosmos::CosmosEntity for MySampleStruct {
-    type Entity = u64;
-
-    fn partition_key(&self) -> Self::Entity {
-        self.number
-    }
-}
-
-#[tokio::main]
-async fn main() -> azure_core::Result<()> {
-    // Let's get Cosmos primary key and account name from env variables.
-    let primary_key =
-        std::env::var("COSMOS_PRIMARY_KEY").expect("Set env variable COSMOS_PRIMARY_KEY first!");
-    let account = std::env::var("COSMOS_ACCOUNT").expect("Set env variable COSMOS_ACCOUNT first!");
-
-    let database_name = std::env::args()
-        .nth(1)
-        .expect("please specify the database name as the first command line parameter");
-    let collection_name = std::env::args()
-        .nth(2)
-        .expect("please specify the collection name as the second command line parameter");
-
-    // First, create an authorization token. There are two types of tokens: primary and resource constrained.
-    // Please check the Azure documentation or the examples folder on how to create and use token-based permissions.
-    let authorization_token = AuthorizationToken::primary_key(&primary_key)?;
-
-    // Next we will create a Cosmos client.
-    let client = CosmosClient::new(account, authorization_token);
-
-    // We know the database so we can obtain a database client.
-    let database = client.database_client(database_name);
-    // We know the collection so we can obtain a collection client.
-    let collection = database.collection_client(collection_name);
-
-    // Insert 10 documents
-    println!("Inserting 10 documents...");
-    for i in 0..10 {
-        // define the document.
-        let document_to_insert = MySampleStruct {
-            id: format!("unique_id{}", i),
-            string: "Something here".to_owned(),
-            number: i * 100, // this is the partition key
-        };
-
-        // insert it
-        collection
-            .create_document(document_to_insert)
-            .is_upsert(true)
-            .await?;
-    }
-
-    Ok(())
-}
-```
-*/
-
 #![warn(unused_extern_crates)]
 #![deny(missing_docs)]
 #![recursion_limit = "256"]

diff --git a/sdk/data_tables/README.md b/sdk/data_tables/README.md
@@ -1,8 +1,15 @@
 # azure_data_tables
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 This crate is from the [Azure SDK for Rust](https://github.com/azure/azure-sdk-for-rust). It supports [Azure Table storage](https://docs.microsoft.com/azure/storage/tables/table-storage-overview).
 
-```rust
+```rust no_run
 use azure_core::StatusCode;
 use azure_data_tables::{operations::InsertEntityResponse, prelude::*};
 use azure_storage::prelude::*;

diff --git a/sdk/data_tables/src/lib.rs b/sdk/data_tables/src/lib.rs
@@ -1,67 +1,4 @@
-/*!
-This crate is from the [Azure SDK for Rust](https://github.com/azure/azure-sdk-for-rust). It supports [Azure Table storage](https://docs.microsoft.com/azure/storage/tables/table-storage-overview).
-
-```no_run
-use azure_core::StatusCode;
-use azure_data_tables::{operations::InsertEntityResponse, prelude::*};
-use azure_storage::prelude::*;
-use futures::stream::StreamExt;
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-struct MyEntity {
-    #[serde(rename = "PartitionKey")]
-    pub city: String,
-    pub name: String,
-    #[serde(rename = "RowKey")]
-    pub surname: String,
-}
-
-#[tokio::main]
-async fn main() -> azure_core::Result<()> {
-    tracing_subscriber::fmt().init();
-
-    // First we retrieve the account name and access key from environment variables.
-    let account =
-        std::env::var("STORAGE_ACCOUNT").expect("Set env variable STORAGE_ACCOUNT first!");
-    let access_key =
-        std::env::var("STORAGE_ACCESS_KEY").expect("Set env variable STORAGE_ACCESS_KEY first!");
-    let table_name = std::env::var("STORAGE_TABLE_NAME").expect("Set env variable STORAGE_TABLE_NAME first!");
-
-    let storage_credentials = StorageCredentials::access_key(account.clone(), access_key);
-    let table_service = TableServiceClient::new(account, storage_credentials);
-
-    let table_client = table_service.table_client(table_name);
-    table_client.create().await?;
-
-    let entity = MyEntity {
-        city: "Milan".to_owned(),
-        name: "Francesco".to_owned(),
-        surname: "A".to_owned(),
-    };
-
-    let _: InsertEntityResponse<MyEntity> = table_client.insert(&entity)?.await?;
-
-    // Get a client that refers to the above entity
-    let entity_client = table_client.partition_key_client(&entity.city).entity_client(&entity.surname);
-
-    // Get an entity from the table
-    let response = entity_client.get().await?;
-    let mut entity: MyEntity = response.entity;
-
-    // update the entity in the table
-    entity.name = "Ryan".to_owned();
-    entity_client.update(&entity, response.etag.into())?.await?;
-    entity_client.delete().await?;
-
-    /// delete the client now that we're done
-    table_client.delete().await?;
-    Ok(())
-}
-
-```
-
-*/
+#![doc = include_str!("../README.md")]
 
 #[macro_use]
 extern crate azure_core;

diff --git a/sdk/identity/README.md b/sdk/identity/README.md
@@ -1,11 +1,18 @@
 # azure_identity
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 Azure Identity crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to [https://github.com/azure/azure-sdk-for-rust](https://github.com/azure/azure-sdk-for-rust).
 
 This crate provides several implementations of the [azure_core::auth::TokenCredential](https://docs.rs/azure_core/latest/azure_core/auth/trait.TokenCredential.html) trait.
 It is recommended to start with `azure_identity::create_credential()?`, which will create an instance of `DefaultAzureCredential` by default. If you want to use a specific credential type, the `AZURE_CREDENTIAL_KIND` environment variable may be set to a value from `azure_credential_kinds`, such as `azurecli` or `virtualmachine`.
 
-```rust
+```rust no_run
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let subscription_id =

diff --git a/sdk/identity/src/lib.rs b/sdk/identity/src/lib.rs
@@ -1,44 +1,4 @@
-//! Azure Identity crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to [https://github.com/azure/azure-sdk-for-rust](https://github.com/azure/azure-sdk-for-rust).
-//!
-//! This crate provides several implementations of the [azure_core::auth::TokenCredential](https://docs.rs/azure_core/latest/azure_core/auth/trait.TokenCredential.html) trait.
-//! It is recommended to start with `azure_identity::create_credential()?`, which will create an instance of `DefaultAzureCredential` by default. If you want to use a specific credential type, the `AZURE_CREDENTIAL_KIND` environment variable may be set to a value from `azure_credential_kinds`, such as `azurecli` or `virtualmachine`.
-//!
-//! ```no_run
-//!#[tokio::main]
-//!async fn main() -> Result<(), Box<dyn std::error::Error>> {
-//!    let subscription_id =
-//!        std::env::var("AZURE_SUBSCRIPTION_ID").expect("AZURE_SUBSCRIPTION_ID required");
-//!
-//!    let credential = azure_identity::create_credential()?;
-//!
-//!    // Let's enumerate the Azure storage accounts in the subscription using the REST API directly.
-//!    // This is just an example. It is easier to use the Azure SDK for Rust crates.
-//!    let url = url::Url::parse(&format!("https://management.azure.com/subscriptions/{subscription_id}/providers/Microsoft.Storage/storageAccounts?api-version=2019-06-01"))?;
-//!
-//!    let access_token = credential
-//!        .get_token(&["https://management.azure.com/.default"])
-//!        .await?;
-//!
-//!    let response = reqwest::Client::new()
-//!        .get(url)
-//!        .header(
-//!            "Authorization",
-//!            format!("Bearer {}", access_token.token.secret()),
-//!        )
-//!        .send()
-//!        .await?
-//!        .text()
-//!        .await?;
-//!
-//!    println!("{response}");
-//!    Ok(())
-//!}
-//! ```
-//!
-//! The supported authentication flows are:
-//! * [Authorization code flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow).
-//! * [Client credentials flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow).
-//! * [Device code flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code).
+#![doc = include_str!("../README.md")]
 
 pub mod authorization_code_flow;
 pub mod client_credentials_flow;

diff --git a/sdk/iot_deviceupdate/README.md b/sdk/iot_deviceupdate/README.md
@@ -1,6 +1,11 @@
 # Azure SDK for Rust - Azure Device Update crate
 
-
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
 
 ## Usage
 

diff --git a/sdk/iot_deviceupdate/src/lib.rs b/sdk/iot_deviceupdate/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod client;
 pub use client::DeviceUpdateClient;
 

diff --git a/sdk/iot_hub/README.md b/sdk/iot_hub/README.md
@@ -1,5 +1,12 @@
 # azure_iot_hub
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 Azure `iot_hub` crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to [https://github.com/azure/azure-sdk-for-rust](https://github.com/azure/azure-sdk-for-rust).
 
 License: MIT
diff --git a/sdk/iot_hub/src/lib.rs b/sdk/iot_hub/src/lib.rs
@@ -1,6 +1,5 @@
-//! Azure `iot_hub` crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to [https://github.com/azure/azure-sdk-for-rust](https://github.com/azure/azure-sdk-for-rust).
+#![doc = include_str!("../README.md")]
 #![deny(missing_docs)]
-//! The `IoT` Hub crate contains a client that can be used to manage the `IoT` Hub.
 
 mod authorization_policy;
 /// The service module contains the `IoT` Hub Service Client that can be used to manage the `IoT` Hub.

diff --git a/sdk/messaging_eventgrid/README.md b/sdk/messaging_eventgrid/README.md
@@ -1,5 +1,12 @@
 # azure_messaging_eventgrid
 
+> Microsoft is developing the official Azure SDK for Rust crates and has no plans to update this unofficial crate.
+> In the future we may release an official version that may have a different package name.
+> If releasing an official version of this crate is important to you [let us know](https://github.com/Azure/azure-sdk-for-rust/issues/new/choose).
+>
+> Source for this crate can now be found in <https://github.com/Azure/azure-sdk-for-rust/tree/legacy>.
+> To monitor for an official, supported version of this crate, see <https://aka.ms/azsdk/releases>.
+
 Azure Messaging Event Grid crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to [https://github.com/azure/azure-sdk-for-rust](https://github.com/azure/azure-sdk-for-rust).
 
 License: MIT
diff --git a/sdk/messaging_eventgrid/src/lib.rs b/sdk/messaging_eventgrid/src/lib.rs
@@ -1,4 +1,5 @@
-//! Azure Messaging Event Grid crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to [https://github.com/azure/azure-sdk-for-rust](https://github.com/azure/azure-sdk-for-rust).
+#![doc = include_str!("../README.md")]
+
 mod event;
 // TODO update event_grid to use HttpClient https://github.com/Azure/azure-sdk-for-rust/issues/254
 // mod event_grid_client;