Add usage to sdk (#467)

* Adding usage to SDK README's to fix #379

* Exit sdk folder

* Grep markdown changes in sdk subfolder

* Fail build if markdown changes exist

Author: deven96

.github/workflows/build.yml

@@ -62,6 +62,14 @@ jobs:
     - name: sdk tests
       run: cargo test --all --features mock_transport_framework
 
+    - name: update readme of sdks
+      run: |
+        cargo install cargo-readme
+        ./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
+
   test-services:
     name: Services Tests
     runs-on: ubuntu-20.04

eng/scripts/cargo_readme.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+cd sdk
+for crate in *
+do
+  if [ -d "$crate" ]; then
+    cd "$crate"
+    echo Updating README.md for "$crate"
+    cargo readme > README.md
+    cd ..
+  fi
+done
+cd ..

sdk/core/README.md

@@ -1,3 +1,12 @@
 # Azure SDK for Rust - Core crate
 
 Core 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).
+
+## Usage
+
+To set this crate as a dependency, add this to your Cargo.toml
+
+```toml
+[dependencies]
+azure_core = { version = "0.1.0", git = "https://github.com/Azure/azure-sdk-for-rust" }
+```

sdk/core/README.tpl

@@ -0,0 +1,12 @@
+# Azure SDK for Rust - Core crate
+
+{{readme}}
+
+## Usage
+
+To set this crate as a dependency, add this to your Cargo.toml
+
+```toml
+[dependencies]
+{{crate}} = { version = "{{version}}", git = "https://github.com/Azure/azure-sdk-for-rust" }
+```

sdk/core/src/lib.rs

@@ -1,3 +1,4 @@
+//! Core 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).
 #![recursion_limit = "256"]
 #![warn(rust_2018_idioms)]
 

sdk/cosmos/README.md

@@ -1,3 +1,101 @@
 # Azure SDK for Rust - Azure Cosmos DB crate
 
-Azure Cosmos DB 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).
+## The Cosmos DB crate.
+
+`azure-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
+
+```rust
+// Using the prelude module of the Cosmos crate makes easier to use the Rust Azure SDK for Cosmos DB.
+use azure_cosmos::prelude::*;
+use azure_core::Context;
+use serde::{Deserialize, Serialize};
+use std::error::Error;
+
+// This is the stuct we want to use in our sample.
+// Make sure to have a collection with partition key "a_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,
+    a_string: String,
+    a_number: u64,
+    a_timestamp: i64,
+}
+
+impl<'a> azure_cosmos::CosmosEntity<'a> for MySampleStruct {
+    type Entity = u64;
+
+    fn partition_key(&'a self) -> Self::Entity {
+        self.a_number
+    }
+}
+
+// This code will perform these tasks:
+// 1. Create 10 documents in the collection.
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
+    // Let's get Cosmos account and master key from env variables.
+    let master_key =
+        std::env::var("COSMOS_MASTER_KEY").expect("Set env variable COSMOS_MASTER_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 first command line parameter");
+    let collection_name = std::env::args()
+        .nth(2)
+        .expect("please specify the collection name as first command line parameter");
+
+    // First, we create an authorization token. There are two types of tokens, master and resource
+    // constrained. This SDK supports both.
+    // Please check the Azure documentation for details or the examples folder
+    // on how to create and use token-based permissions.
+    let authorization_token = AuthorizationToken::primary_from_base64(&master_key)?;
+
+    // Next we will create a Cosmos client.
+    let client = CosmosClient::new(account.clone(), authorization_token, CosmosOptions::default());
+
+    // We know the database so we can obtain a database client.
+    let database_client = client.into_database_client(database_name);
+    // We know the collection so we can obtain a collection client.
+    let collection_client = database_client.into_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),
+            a_string: "Something here".to_owned(),
+            a_number: i * 100, // this is the partition key
+            a_timestamp: chrono::Utc::now().timestamp(),
+        };
+
+        // insert it
+        collection_client
+            .create_document(
+                Context::new(),
+                &document_to_insert,
+                CreateDocumentOptions::new().is_upsert(true),
+            )
+            .await?;
+    }
+    // wow that was easy and fast, wasn't it? :)
+    println!("Done!");
+
+    Ok(())
+}
+```
+
+## Usage
+
+To set this crate as a dependency, add this to your Cargo.toml
+
+```toml
+[dependencies]
+azure_cosmos = { version = "0.1.0", git = "https://github.com/Azure/azure-sdk-for-rust" }
+```

sdk/cosmos/README.tpl

@@ -0,0 +1,12 @@
+# Azure SDK for Rust - Azure Cosmos DB crate
+
+{{readme}}
+
+## Usage
+
+To set this crate as a dependency, add this to your Cargo.toml
+
+```toml
+[dependencies]
+{{crate}} = { version = "{{version}}", git = "https://github.com/Azure/azure-sdk-for-rust" }
+```

sdk/cosmos/src/lib.rs

@@ -89,7 +89,7 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
     Ok(())
 }
 ```
-!*/
+*/
 
 #![warn(unused_extern_crates)]
 #![deny(missing_docs)]

sdk/identity/README.md

@@ -1,3 +1,55 @@
 # Azure SDK for Rust - Azure OAuth2 Crate
 
-Azure OAuth2 helper 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).
+ Azure OAuth2 helper 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 mechanisms for several ways to authenticate against Azure
+
+For example, to authenticate using the client credential flow, you can do the following:
+
+```rust
+use azure_identity::client_credentials_flow;
+use oauth2::{ClientId, ClientSecret};
+use url::Url;
+
+use std::env;
+use std::error::Error;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let client_id =
+        ClientId::new(env::var("CLIENT_ID").expect("Missing CLIENT_ID environment variable."));
+    let client_secret = ClientSecret::new(
+        env::var("CLIENT_SECRET").expect("Missing CLIENT_SECRET environment variable."),
+    );
+    let tenant_id = env::var("TENANT_ID").expect("Missing TENANT_ID environment variable.");
+    let subscription_id =
+        env::var("SUBSCRIPTION_ID").expect("Missing SUBSCRIPTION_ID environment variable.");
+
+    let client = reqwest::Client::new();
+    // This will give you the final token to use in authorization.
+    let token = client_credentials_flow::perform(
+        client,
+        &client_id,
+        &client_secret,
+        "https://management.azure.com/",
+        &tenant_id,
+    )
+    .await?;
+    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).
+
+This crate also includes utilities for handling refresh tokens and accessing token credentials from many different sources.
+
+## Usage
+
+To set this crate as a dependency, add this to your Cargo.toml
+
+```toml
+[dependencies]
+azure_identity = { version = "0.1.0", git = "https://github.com/Azure/azure-sdk-for-rust" }
+```

sdk/identity/README.tpl

@@ -0,0 +1,12 @@
+# Azure SDK for Rust - Azure OAuth2 Crate
+
+{{readme}}
+
+## Usage
+
+To set this crate as a dependency, add this to your Cargo.toml
+
+```toml
+[dependencies]
+{{crate}} = { version = "{{version}}", git = "https://github.com/Azure/azure-sdk-for-rust" }
+```