add links & README.md for services (Azure#695)

Co-authored-by: Cameron Taggart <cameron.taggart@gmail.com>
Co-authored-by: Heath Stewart <heaths@outlook.com>

Author: 3 people

services/CHANGELOG.md

@@ -3,6 +3,7 @@
 - [#672](https://github.com/Azure/azure-sdk-for-rust/pull/672) generated from azure-rest-api-specs [commit from 2022-03-02](https://github.com/Azure/azure-rest-api-specs/commit/c56b44b794ff17caad4d31c6ab64b07e28253504)
 - [#675](https://github.com/Azure/azure-sdk-for-rust/pull/675) use Basic Information tag for default version
 - [#634](https://github.com/Azure/azure-sdk-for-rust/issues/634) limit docs.rs to 5 API tags
+- [#632](https://github.com/Azure/azure-sdk-for-rust/issues/632) add links & README.md for services
 
 # 0.1 (2022-01)
 

services/autorust/.gitignore

@@ -8,3 +8,4 @@ model*.rs
 generated
 node_modules
 package*.json
+gen_readme.md

services/autorust/codegen/Cargo.toml

@@ -3,6 +3,7 @@ name = "autorust_codegen"
 version = "0.1.0"
 authors = ["Cameron Taggart <cameron.taggart@gmail.com>"]
 edition = "2018"
+publish = false
 
 [lib]
 
@@ -23,3 +24,4 @@ http = "0.2"
 once_cell = "1.7"
 syn = { version = "1.0", features = ["parsing"] }
 camino = "1.0"
+askama = "0.11"

services/autorust/codegen/examples/gen_mgmt.rs

@@ -1,7 +1,12 @@
 // cargo run --example gen_mgmt --release
 // https://github.com/Azure/azure-rest-api-specs/blob/master/specification/compute/resource-manager
-use autorust_codegen::{self, cargo_toml, get_mgmt_readmes, lib_rs, path, Config, PropertyName, SpecReadme};
-use std::{collections::HashSet, fs, path::PathBuf};
+use autorust_codegen::{
+    self, cargo_toml, get_mgmt_readmes, io, lib_rs,
+    readme_md::{self, ReadmeMd},
+    Config, Error, PropertyName, Result, SpecReadme,
+};
+use camino::Utf8PathBuf;
+use std::{collections::HashSet, fs};
 
 const OUTPUT_FOLDER: &str = "../mgmt";
 
@@ -293,24 +298,6 @@ const BOX_PROPERTIES: &[(&str, &str, &str)] = &[
     ("../../../azure-rest-api-specs/specification/keyvault/resource-manager/Microsoft.KeyVault/stable/2021-10-01/managedHsm.json", "Error", "innererror"),
 ];
 
-pub type Result<T, E = Error> = std::result::Result<T, E>;
-
-#[derive(Debug, thiserror::Error)]
-pub enum Error {
-    #[error(transparent)]
-    CodegenError(#[from] autorust_codegen::Error),
-    #[error("file name was not utf-8")]
-    FileNameNotUtf8Error {},
-    #[error("IoError")]
-    IoError { source: std::io::Error },
-    #[error("PathError")]
-    PathError { source: path::Error },
-    #[error("CargoTomlError")]
-    CargoTomlError { source: cargo_toml::Error },
-    #[error("LibRsError")]
-    LibRsError { source: lib_rs::Error },
-}
-
 fn main() -> Result<()> {
     for (i, spec) in get_mgmt_readmes()?.iter().enumerate() {
         if !ONLY_SERVICES.is_empty() {
@@ -329,11 +316,11 @@ fn main() -> Result<()> {
 fn gen_crate(spec: &SpecReadme) -> Result<()> {
     let service_name = &spec.service_name();
     let crate_name = &format!("azure_mgmt_{}", service_name);
-    let output_folder = &path::join(OUTPUT_FOLDER, service_name).map_err(|source| Error::PathError { source })?;
+    let output_folder = &io::join(OUTPUT_FOLDER, service_name)?;
 
-    let src_folder = path::join(output_folder, "src").map_err(|source| Error::PathError { source })?;
+    let src_folder = io::join(output_folder, "src")?;
     if src_folder.exists() {
-        fs::remove_dir_all(&src_folder).map_err(|source| Error::IoError { source })?;
+        fs::remove_dir_all(&src_folder)?;
     }
 
     let mut tags = Vec::new();
@@ -342,7 +329,7 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
     let mut box_properties = HashSet::new();
     for (file_path, schema_name, property_name) in BOX_PROPERTIES {
         box_properties.insert(PropertyName {
-            file_path: PathBuf::from(file_path),
+            file_path: Utf8PathBuf::from(file_path),
             schema_name: schema_name.to_string(),
             property_name: property_name.to_string(),
         });
@@ -351,7 +338,7 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
     let mut optional_properties = HashSet::new();
     for (file_path, schema_name, property_name) in OPTIONAL_PROPERTIES {
         optional_properties.insert(PropertyName {
-            file_path: PathBuf::from(file_path),
+            file_path: Utf8PathBuf::from(file_path),
             schema_name: schema_name.to_string(),
             property_name: property_name.to_string(),
         });
@@ -365,12 +352,12 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
             continue;
         }
         println!("  {}", tag_name);
-        let mod_output_folder = path::join(&src_folder, &tag.rust_mod_name()).map_err(|source| Error::PathError { source })?;
+        let mod_output_folder = io::join(&src_folder, &tag.rust_mod_name())?;
         tags.push(tag);
         let input_files: Result<Vec<_>> = tag
             .input_files()
             .iter()
-            .map(|input_file| path::join(spec.readme(), input_file).map_err(|source| Error::PathError { source }))
+            .map(|input_file| io::join(spec.readme(), input_file).map_err(Error::from))
             .collect();
         let input_files = input_files?;
         autorust_codegen::run(Config {
@@ -385,19 +372,14 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
     if tags.is_empty() {
         return Ok(());
     }
-    cargo_toml::create(
+    cargo_toml::create(crate_name, &tags, config.tag(), &io::join(output_folder, "Cargo.toml")?)?;
+    lib_rs::create(&tags, &io::join(src_folder, "lib.rs")?, false)?;
+
+    let readme = ReadmeMd {
         crate_name,
-        &tags,
-        config.tag(),
-        &path::join(output_folder, "Cargo.toml").map_err(|source| Error::PathError { source })?,
-    )
-    .map_err(|source| Error::CargoTomlError { source })?;
-    lib_rs::create(
-        &tags,
-        &path::join(src_folder, "lib.rs").map_err(|source| Error::PathError { source })?,
-        false,
-    )
-    .map_err(|source| Error::LibRsError { source })?;
+        readme_url: readme_md::url(spec.readme().as_str()),
+    };
+    readme.create(&io::join(output_folder, "README.md")?)?;
 
     Ok(())
 }

services/autorust/codegen/examples/gen_svc.rs

@@ -1,11 +1,12 @@
 // cargo run --example gen_svc --release
 // https://github.com/Azure/azure-rest-api-specs/blob/master/specification/batch/data-plane
 use autorust_codegen::{
-    self,
-    cargo_toml::{self},
-    get_svc_readmes, lib_rs, path, Config, PropertyName, SpecReadme,
+    self, cargo_toml, get_svc_readmes, io, lib_rs,
+    readme_md::{self, ReadmeMd},
+    Config, Error, PropertyName, Result, SpecReadme,
 };
-use std::{collections::HashSet, fs, path::PathBuf};
+use camino::Utf8PathBuf;
+use std::{collections::HashSet, fs};
 
 const OUTPUT_FOLDER: &str = "../svc";
 
@@ -166,24 +167,6 @@ const BOX_PROPERTIES: &[(&str, &str, &str)] = &[
     ),
 ];
 
-pub type Result<T, E = Error> = std::result::Result<T, E>;
-
-#[derive(Debug, thiserror::Error)]
-pub enum Error {
-    #[error(transparent)]
-    CodegenError(#[from] autorust_codegen::Error),
-    #[error("file name was not utf-8")]
-    FileNameNotUtf8Error {},
-    #[error("IoError")]
-    IoError { source: std::io::Error },
-    #[error("PathError")]
-    PathError { source: path::Error },
-    #[error("CargoTomlError")]
-    CargoTomlError { source: cargo_toml::Error },
-    #[error("LibRsError")]
-    LibRsError { source: lib_rs::Error },
-}
-
 fn main() -> Result<()> {
     for (i, spec) in get_svc_readmes()?.iter().enumerate() {
         if !ONLY_SERVICES.is_empty() {
@@ -210,11 +193,11 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
 
     let service_name = &spec.service_name();
     let crate_name = &format!("azure_svc_{}", service_name);
-    let output_folder = &path::join(OUTPUT_FOLDER, service_name).map_err(|source| Error::PathError { source })?;
+    let output_folder = &io::join(OUTPUT_FOLDER, service_name)?;
 
-    let src_folder = path::join(output_folder, "src").map_err(|source| Error::PathError { source })?;
+    let src_folder = io::join(output_folder, "src")?;
     if src_folder.exists() {
-        fs::remove_dir_all(&src_folder).map_err(|source| Error::IoError { source })?;
+        fs::remove_dir_all(&src_folder)?;
     }
 
     let mut tags = Vec::new();
@@ -227,7 +210,7 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
     let mut box_properties = HashSet::new();
     for (file_path, schema_name, property_name) in BOX_PROPERTIES {
         box_properties.insert(PropertyName {
-            file_path: PathBuf::from(file_path),
+            file_path: Utf8PathBuf::from(file_path),
             schema_name: schema_name.to_string(),
             property_name: property_name.to_string(),
         });
@@ -236,7 +219,7 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
     let mut invalid_types = HashSet::new();
     for (file_path, schema_name, property_name) in INVALID_TYPE_WORKAROUND {
         invalid_types.insert(PropertyName {
-            file_path: PathBuf::from(file_path),
+            file_path: Utf8PathBuf::from(file_path),
             schema_name: schema_name.to_string(),
             property_name: property_name.to_string(),
         });
@@ -250,12 +233,12 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
         }
         println!("  {}", tag_name);
         let mod_name = tag.rust_mod_name();
-        let mod_output_folder = path::join(&src_folder, &mod_name).map_err(|source| Error::PathError { source })?;
+        let mod_output_folder = io::join(&src_folder, &mod_name)?;
         tags.push(tag);
         let input_files: Result<Vec<_>> = tag
             .input_files()
             .iter()
-            .map(|input_file| path::join(spec.readme(), input_file).map_err(|source| Error::PathError { source }))
+            .map(|input_file| io::join(spec.readme(), input_file).map_err(Error::from))
             .collect();
         let input_files = input_files?;
         autorust_codegen::run(Config {
@@ -271,19 +254,14 @@ fn gen_crate(spec: &SpecReadme) -> Result<()> {
     if tags.is_empty() {
         return Ok(());
     }
-    cargo_toml::create(
+    cargo_toml::create(crate_name, &tags, config.tag(), &io::join(output_folder, "Cargo.toml")?)?;
+    lib_rs::create(&tags, &io::join(src_folder, "lib.rs")?, false)?;
+
+    let readme = ReadmeMd {
         crate_name,
-        &tags,
-        config.tag(),
-        &path::join(output_folder, "Cargo.toml").map_err(|source| Error::PathError { source })?,
-    )
-    .map_err(|source| Error::CargoTomlError { source })?;
-    lib_rs::create(
-        &tags,
-        &path::join(src_folder, "lib.rs").map_err(|source| Error::PathError { source })?,
-        false,
-    )
-    .map_err(|source| Error::LibRsError { source })?;
+        readme_url: readme_md::url(spec.readme().as_str()),
+    };
+    readme.create(&io::join(output_folder, "README.md")?)?;
 
     Ok(())
 }

services/autorust/codegen/examples/mgmt_tags.rs

@@ -2,7 +2,7 @@
 // prints all the mgmt (control plane, resource-manager) tags
 
 use autorust_codegen::get_mgmt_readmes;
-pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
+use autorust_codegen::Result;
 
 fn main() -> Result<()> {
     let mut tag_count = 0;
@@ -11,7 +11,7 @@ fn main() -> Result<()> {
         for tag in spec.config()?.tags() {
             println!("  {}", &tag.name());
             for input_file in &tag.input_files() {
-                println!("    {}", input_file.display());
+                println!("    {}", input_file);
             }
             tag_count += 1;
         }

services/autorust/codegen/examples/multiple_versions.rs

@@ -3,11 +3,9 @@
 // in general, we want to avoid this
 // https://github.com/Azure/azure-sdk-for-rust/issues/563
 
-use autorust_codegen::{get_mgmt_readmes, get_svc_readmes, path, Spec, SpecReadme};
+use autorust_codegen::{get_mgmt_readmes, get_svc_readmes, io, Result, Spec, SpecReadme};
 use std::collections::BTreeSet;
 
-pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
-
 fn main() -> Result<()> {
     println!("CONTROL PLANE");
     check(&get_mgmt_readmes()?)?;
@@ -23,7 +21,7 @@ fn check(readmes: &[SpecReadme]) -> Result<()> {
     for readme in readmes {
         let readme_path = readme.readme();
         for tag in readme.config()?.tags() {
-            let input_files = path::join_several(readme_path, &tag.input_files())?;
+            let input_files = io::join_several(readme_path, &tag.input_files())?;
             match Spec::read_files(&input_files) {
                 Ok(spec) => {
                     let versions = spec.api_versions();

services/autorust/codegen/examples/svc_tags.rs

@@ -1,8 +1,8 @@
 // cargo run --example svc_tags
 // prints all the svc (data plane) tags
 
+use autorust_codegen::Result;
 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;
@@ -11,7 +11,7 @@ fn main() -> Result<()> {
         for tag in spec.config()?.tags() {
             println!("  {}", &tag.name());
             for input_file in &tag.input_files() {
-                println!("    {}", input_file.display());
+                println!("    {}", input_file);
             }
             tag_count += 1;
         }

services/autorust/codegen/src/cargo_toml.rs

@@ -1,19 +1,24 @@
 use crate::config_parser::Tag;
+use camino::Utf8Path;
 use std::{
     fs::File,
     io::{prelude::*, LineWriter},
-    path::Path,
 };
 
 pub type Result<T, E = Error> = std::result::Result<T, E>;
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
-    #[error("IoError")]
-    IoError { source: std::io::Error },
+    #[error(transparent)]
+    Io(crate::io::Error),
+}
+impl<T: Into<crate::io::Error>> From<T> for Error {
+    fn from(error: T) -> Self {
+        Self::Io(error.into())
+    }
 }
 
-pub fn create(crate_name: &str, tags: &[&Tag], default_tag: Option<&str>, path: &Path) -> Result<()> {
-    let file = File::create(path).map_err(|source| Error::IoError { source })?;
+pub fn create(crate_name: &str, tags: &[&Tag], default_tag: Option<&str>, path: &Utf8Path) -> Result<()> {
+    let file = File::create(path)?;
     let mut file = LineWriter::new(file);
     let default_feature = get_default_feature(tags, default_tag);
 
@@ -28,9 +33,12 @@ pub fn create(crate_name: &str, tags: &[&Tag], default_tag: Option<&str>, path:
 [package]
 name = "{}"
 version = "0.2.0"
-edition = "2018"
+edition = "2021"
 license = "MIT"
 description = "generated REST API bindings"
+repository = "https://github.com/azure/azure-sdk-for-rust"
+homepage = "https://github.com/azure/azure-sdk-for-rust"
+documentation = "https://docs.rs/{}"
 
 [dependencies]
 azure_core = {{ path = "../../../sdk/core", version = "0.1", default-features = false }}
@@ -55,15 +63,13 @@ enable_reqwest = ["azure_core/enable_reqwest"]
 enable_reqwest_rustls = ["azure_core/enable_reqwest_rustls"]
 no-default-version = []
 "#,
-            crate_name, docs_rs_features, default_feature
+            crate_name, crate_name, docs_rs_features, default_feature
         )
         .as_bytes(),
-    )
-    .map_err(|source| Error::IoError { source })?;
+    )?;
 
     for tag in tags {
-        file.write_all(format!("\"{}\" = []\n", tag.rust_feature_name()).as_bytes())
-            .map_err(|source| Error::IoError { source })?;
+        file.write_all(format!("\"{}\" = []\n", tag.rust_feature_name()).as_bytes())?;
     }
     Ok(())
 }