Improve README and documentation for remi-azure, added `export-azur…

…e` feature

crates/azure/Cargo.toml

@@ -21,15 +21,20 @@
 
 [package]
 name = "remi-azure"
-description = "🐻‍❄️🧶 Azure Blob Storage implementation of `remi-rs`"
+description = "🐻‍❄️🧶 Support of Microsoft's Azure Blob Storage with remi-rs primitives"
 version.workspace = true
 repository.workspace = true
 license.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(noeldoc)'] }
+
 [features]
-default = ["serde"]
+default = ["export-azure"]
+
+export-azure = []
 tracing = ["dep:tracing"]
 serde = ["dep:serde"]
 log = ["dep:log"]

crates/azure/README.md

@@ -1,12 +1,65 @@
-# 🐻‍❄️🧶 Microsoft Azure Blob Storage Support for `remi-rs`
-**remi-azure** is an official implementation of using Remi with Microsoft Azure Blob Storage by Noelware.
+<div align="center">
+    <h4>Official and maintained <code>remi-rs</code> crate for support of Microsoft's Azure Blob Storage</h4>
+    <hr />
+    <kbd><a href="https://github.com/Noelware/remi-rs/releases/0.9.0">v0.9.0</a></kbd> | <a href="https://docs.rs/remi">:scroll: Documentation</a>
+</div>
 
-## Features
-### serde (disabled)
-Enables the use of [`serde`](https://docs.rs/serde) for (de)serializing for configuration files.
+| Crate Features | Description                                                                          | Enabled by default? |
+| :------------- | :----------------------------------------------------------------------------------- | ------------------- |
+| `export-azure` | Exports all the used Azure crates as a module called `core`                          | Yes.                |
+| [`tracing`]    | Enables the use of [`tracing::instrument`] and emit events for actions by the crate. | No.                 |
+| [`serde`]      | Enables the use of **serde** in `StorageConfig`                                      | No.                 |
+| [`log`]        | Emits log records for actions by the crate                                           | No.                 |
 
-### log (disabled)
-Enables the use of [`log`](https://docs.rs/log) for adding unstructured logging events to track down why something broke.
+## Example
+```rust,no_run
+// Cargo.toml:
+//
+// [dependencies]
+// remi = "^0"
+// remi-azure = "^0"
+// tokio = { version = "^1", features = ["full"] }
 
-### tracing (disabled)
-Enables the use of [`tracing::instrument`](https://docs.rs/tracing/*/tracing/attr.instrument.html) for adding spans to method calls to track down why something went wrong or to debug performance hits.
+use remi_azure::{StorageService, StorageConfig, Credential, core};
+use remi::{StorageService as _, UploadRequest};
+
+#[tokio::main]
+async fn main() {
+    let storage = StorageService::new(StorageConfig {
+        credential: Credential::Anonymous,
+        location: core::storage::CloudLocation::Public,
+        container: "my-container".into(),
+    });
+
+    // Initialize the container. This will:
+    //
+    // * create `my-container` if it doesn't exist
+    storage.init().await.unwrap();
+
+    // Now we can upload files to Azure.
+
+    // We define a `UploadRequest`, which will set the content type to `text/plain` and set the
+    // contents of `weow.txt` to `weow fluff`.
+    let upload = UploadRequest::default()
+        .with_content_type(Some("text/plain"))
+        .with_data("weow fluff");
+
+    // Let's upload it!
+    storage.upload("weow.txt", upload).await.unwrap();
+
+    // Let's check if it exists! This `assert!` will panic if it failed
+    // to upload.
+    assert!(storage.exists("weow.txt").await.unwrap());
+
+    // Now we can query multiple "blobs"
+    //
+    // remi-rs defines blobs as either a directory or a file, since
+    // Azure only lets us look up files as files, all of them will
+    // be of `Blob::File`.
+}
+```
+
+[`tracing::instrument`]: https://docs.rs/tracing/*/tracing/attr.instrument.html
+[`tracing`]: https://crates.io/crates/tracing
+[`serde`]: https://serde.rs
+[`log`]: https://crates.io/crates/log

crates/azure/src/lib.rs

@@ -20,8 +20,28 @@
 // SOFTWARE.
 
 #![doc(html_logo_url = "https://cdn.floofy.dev/images/trans.png")]
+#![cfg_attr(any(noeldoc, docsrs), feature(doc_cfg))]
 #![doc = include_str!("../README.md")]
 
+#[cfg(feature = "export-azure")]
+#[cfg_attr(any(noeldoc, docsrs), doc(cfg(feature = "export-azure")))]
+/// Exports the [`azure_core`], [`azure_storage`], and [`azure_storage_blobs`]
+/// crates without defining them as owned dependencies.
+pub mod core {
+    pub use azure_core::*;
+
+    /// Exports the [`azure_storage`] and [`azure_storage_blobs`]
+    /// crates without defining them as owned dependencies.
+    pub mod storage {
+        pub use azure_storage::*;
+
+        /// Exports the [`azure_storage_blobs`] crate without defining them as owned dependencies.
+        pub mod blobs {
+            pub use azure_storage_blobs::*;
+        }
+    }
+}
+
 mod config;
 pub use config::*;