docs: Polish docs for better reading (#1288)

Signed-off-by: Xuanwo <[email protected]>

README.md

@@ -62,55 +62,40 @@ Access data **efficiently**
 ## Quickstart
 
 ```rust
-use anyhow::Result;
-use futures::StreamExt;
-use futures::TryStreamExt;
-use opendal::ObjectReader;
-use opendal::Object;
-use opendal::ObjectMetadata;
-use opendal::ObjectMode;
-use opendal::Operator;
+use opendal::Result;
+use opendal::layers::LoggingLayer;
 use opendal::services;
+use opendal::Operator;
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Init Operator
-    let op = Operator::create(services::Fs::default())?.finish();
+    // Pick a builder and configure it.
+    let mut builder = services::S3::default();
+    builder.bucket("test");
+
+    // Init an operator
+    let op = Operator::create(builder)?
+        // Init with logging layer enabled.
+        .layer(LoggingLayer::default())
+        .finish();
 
     // Create object handler.
-    let o = op.object("/tmp/test_file");
+    let o = op.object("test_file");
 
-    // Write data info object;
+    // Write data
     o.write("Hello, World!").await?;
 
-    // Read data from object;
+    // Read data
     let bs = o.read().await?;
 
-    // Read range from object;
-    let bs = o.range_read(1..=11).await?;
-
-    // Get object's path
-    let name = o.name();
-    let path = o.path();
-
-    // Fetch more meta about object.
+    // Fetch metadata
     let meta = o.metadata().await?;
     let mode = meta.mode();
     let length = meta.content_length();
-    let content_md5 = meta.content_md5();
-    let etag = meta.etag();
 
-    // Delete object.
+    // Delete
     o.delete().await?;
 
-    // List dir object.
-    let o = op.object("test_dir/");
-    let mut os = o.list().await?;
-    while let Some(entry) = os.try_next().await? {
-        let path = entry.path();
-        let mode = entry.mode().await?;
-    }
-
     Ok(())
 }
 ```

src/docs/features.md

@@ -0,0 +1,24 @@
+default feature is `rustls` which enable rustls support.
+
+## Layer Features
+
+- `layers-all`: Enable all layers support.
+- `layers-metrics`: Enable metrics layer support.
+- `layers-tracing`: Enable tracing layer support.
+- `layers-chaos`: Enable chaos layer support.
+
+## Service Features
+
+- `services-ftp`: Enable ftp service support.
+- `services-hdfs`: Enable hdfs service support.
+- `services-moka`: Enable moka service support.
+- `services-ipfs`: Enable ipfs service support.
+- `services-redis`: Enable redis service support.
+- `services-rocksdb`: Enable rocksdb service support.
+
+## Dependencies Features
+
+- `compress`: Enable object decompress read support.
+- `rustls`: Enable TLS functionality provided by `rustls`, enabled by default
+- `native-tls`: Enable TLS functionality provided by `native-tls`
+- `native-tls-vendored`: Enable the `vendored` feature of `native-tls`

src/docs/mod.rs

@@ -20,12 +20,18 @@ pub mod comparisons;
 
 pub mod concepts;
 
+/// Changes log for all OpenDAL released versions.
 #[doc = include_str!("../../CHANGELOG.md")]
 pub mod changelog {}
 
+/// All features that provided by OpenDAL.
+#[doc = include_str!("features.md")]
+pub mod features {}
+
 #[cfg(not(doctest))]
 pub mod rfcs;
 
-#[cfg(not(doctest))]
+/// Upgrade and migrate procedures while OpenDAL meets breaking changes.
 #[doc = include_str!("upgrade.md")]
+#[cfg(not(doctest))]
 pub mod upgrade {}

src/docs/upgrade.md

@@ -1,5 +1,3 @@
-Upgrade and migrate procedures while OpenDAL meets breaking changes.
-
 # Upgrade to v0.26
 
 In v0.26 we have replaced all internal dynamic dispatch usage with static dispatch. With this change, we can ensure that all operations performed inside OpenDAL are zero cost.

src/layers/chaos.rs

@@ -25,7 +25,7 @@ use rand::rngs::StdRng;
 use crate::raw::*;
 use crate::*;
 
-/// ChaosLayer will inject chaos into underlying services.
+/// Inject chaos into underlying services for robustness test.
 ///
 /// # Chaos
 ///

src/layers/concurrent_limit.rs

@@ -26,7 +26,7 @@ use tokio::sync::Semaphore;
 use crate::raw::*;
 use crate::*;
 
-/// ConcurrentLimitLayer will add concurrent limit for OpenDAL.
+/// Add concurrent request limit.
 ///
 /// # Examples
 ///

src/layers/immutable_index.rs

@@ -23,8 +23,7 @@ use crate::object::*;
 use crate::raw::*;
 use crate::*;
 
-/// ImmutableIndexLayer is used to add an immutable in-memory index for
-/// underlying storage services.
+/// Add an immutable in-memory index for underlying storage services.
 ///
 /// Especially useful for services without list capability like HTTP.
 ///

src/layers/logging.rs

@@ -32,7 +32,7 @@ use log::Level;
 use crate::raw::*;
 use crate::*;
 
-/// LoggingLayer will add logging for OpenDAL.
+/// Add [log](https://docs.rs/log/) for every operations.
 ///
 /// # Logging
 ///

src/layers/metrics.rs

@@ -61,7 +61,7 @@ static LABEL_OPERATION: &str = "operation";
 /// The error kind of this failed request.
 static LABEL_ERROR: &str = "error";
 
-/// MetricsLayer will add metrics for OpenDAL.
+/// Add [metrics](https://docs.rs/metrics/) for every operations.
 ///
 /// # Metrics
 ///

src/layers/mod.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Providing Layer implementations.
+//! `Layer` is the mechanism to intercept operations.
 
 mod concurrent_limit;
 pub use concurrent_limit::ConcurrentLimitLayer;

src/layers/retry.rs

@@ -25,7 +25,7 @@ use log::warn;
 use crate::raw::*;
 use crate::*;
 
-/// RetryLayer will add retry for OpenDAL.
+/// Add retry for temporary failed operations.
 ///
 /// # Examples
 ///

src/layers/tracing.rs

@@ -28,7 +28,7 @@ use tracing::Span;
 use crate::raw::*;
 use crate::*;
 
-/// TracingLayer will add tracing for OpenDAL.
+/// Add [tracing](https://docs.rs/tracing/) for every operations.
 ///
 /// # Examples
 ///

src/lib.rs

@@ -14,108 +14,29 @@
 
 //! OpenDAL is the Open Data Access Layer to **freely**, **painlessly**, and **efficiently** access data.
 //!
-//! # Documentation
+//! - Documentation: All docs are carried byself, visit [`docs`] for more.
+//! - Services: All supported services could be found at [`services`].
+//! - Layers: All builtin layer could be found at [`layers`].
+//! - Features: All features could be found at [`features`][docs::features].
 //!
-//! OpenDAL carries all it's documentation in crate itself.
-//!
-//! More docs about OpenDAL could be found at [`docs`].
-//!
-//! # Services
-//!
-//! `Service` represents a backend scheme that OpenDAL supported.
-//!
-//! OpenDAL supports the following services now:
-//!
-//! | Services | Description |
-//! | -------- | ----------- |
-//! | [azblob][services::Azblob] | Azure Storage Blob services. |
-//! | [azdfs][services::Azdfs] | Azure Data Lake Storage Gen2 services. |
-//! | [fs][services::Fs] | POSIX alike file system. |
-//! | [ftp][services::Ftp] | FTP and FTPS support. |
-//! | [gcs][services::Gcs] | Google Cloud Storage service. |
-//! | [ghac][services::Ghac] | Github Action Cache service. |
-//! | [hdfs][services::Hdfs] | Hadoop Distributed File System(HDFS). |
-//! | [http][services::Http] | HTTP read-only backend. |
-//! | [ipfs][services::Ipfs] | IPFS HTTP Gateway support. |
-//! | [ipmfs][services::Ipmfs] | IPFS Mutable File System support. |
-//! | [memcached][services::Memcached] | Memcached service. |
-//! | [memory][services::Memory] | In memory backend support. |
-//! | [moka][services::Moka] | [moka](https://github.com/moka-rs/moka) backend support. |
-//! | [obs][services::Obs] | Huawei Cloud OBS service. |
-//! | [oss][services::Oss] | Aliyun Object Storage Service (OSS).|
-//! | [redis][services::Redis] | Redis service. |
-//! | [rocksdb][services::Rocksdb] | RocksDB service. |
-//! | [s3][services::S3] | AWS S3 alike services. |
-//! | [webdav][services::Webdav] | WebDAV services. |
-//!
-//! - Different services capabilities could be found at [`services`]
-//! - More services support is tracked at [opendal#5](https://github.com/datafuselabs/opendal/issues/5)
-//!
-//! # Layers
-//!
-//! `Layer` is the mechanism to intercept operations.
-//!
-//! OpenDAL supports the following layers now:
-//!
-//! | Layers | Description |
-//! | -------- | ----------- |
-//! | [ChaosLayer][layers::ChaosLayer] | Inject chaos into underlying services. |
-//! | [ConcurrentLimitLayer][layers::ConcurrentLimitLayer] | Concurrent request limit. |
-//! | [ImmutableIndexLayer][layers::ImmutableIndexLayer] | Immutable in-memory index. |
-//! | [LoggingLayer][layers::LoggingLayer] | Logging for every operations. |
-//! | [MetricsLayer][layers::MetricsLayer] | Metrics for every operations. |
-//! | [RetryLayer][layers::RetryLayer] | Retry for failed operations. |
-//! | [TracingLayer][layers::TracingLayer] | Tracing for every operations. |
-//!
-//! # Optional features
-//!
-//! ## Layers
-//!
-//! - `layers-all`: Enable all layers support.
-//! - `layers-metrics`: Enable metrics layer support.
-//! - `layers-tracing`: Enable tracing layer support.
-//! - `layers-chaos`: Enable chaos layer support.
-//!
-//! ## Services
-//!
-//! - `services-ftp`: Enable ftp service support.
-//! - `services-hdfs`: Enable hdfs service support.
-//! - `services-moka`: Enable moka service support.
-//! - `services-ipfs`: Enable ipfs service support.
-//! - `services-redis`: Enable redis service support.
-//! - `services-rocksdb`: Enable rocksdb service support.
-//!
-//! ## Dependencies features
-//!
-//! - `compress`: Enable object decompress read support.
-//! - `rustls`: Enable TLS functionality provided by `rustls`, enabled by default
-//! - `native-tls`: Enable TLS functionality provided by `native-tls`
-//! - `native-tls-vendored`: Enable the `vendored` feature of `native-tls`
-//!
-//! # Examples
+//! # Quick Start
 //!
 //! ```no_run
-//! use anyhow::Result;
-//! use backon::ExponentialBackoff;
-//! use futures::StreamExt;
-//! use futures::TryStreamExt;
+//! use opendal::Result;
 //! use opendal::layers::LoggingLayer;
-//! use opendal::layers::RetryLayer;
 //! use opendal::services;
-//! use opendal::Object;
-//! use opendal::ObjectMetadata;
-//! use opendal::ObjectMode;
 //! use opendal::Operator;
-//! use opendal::Scheme;
 //!
 //! #[tokio::main]
 //! async fn main() -> Result<()> {
-//!     // Init a fs operator
-//!     let op = Operator::from_env::<services::Fs>()?
+//!     // Pick a builder and configure it.
+//!     let mut builder = services::S3::default();
+//!     builder.bucket("test");
+//!
+//!     // Init an operator
+//!     let op = Operator::create(builder)?
 //!         // Init with logging layer enabled.
 //!         .layer(LoggingLayer::default())
-//!         // Init with retry layer enabled.
-//!         .layer(RetryLayer::new(ExponentialBackoff::default()))
 //!         .finish();
 //!
 //!     // Create object handler.
@@ -128,23 +49,13 @@
 //!     let bs = o.read().await?;
 //!
 //!     // Fetch metadata
-//!     let name = o.name();
-//!     let path = o.path();
 //!     let meta = o.metadata().await?;
 //!     let mode = meta.mode();
 //!     let length = meta.content_length();
 //!
 //!     // Delete
 //!     o.delete().await?;
 //!
-//!     // Readdir
-//!     let o = op.object("test_dir/");
-//!     let mut ds = o.list().await?;
-//!     while let Some(entry) = ds.try_next().await? {
-//!         let path = entry.path();
-//!         let mode = entry.mode().await?;
-//!     }
-//!
 //!     Ok(())
 //! }
 //! ```

src/services/azblob/backend.rs

@@ -39,6 +39,17 @@ const X_MS_BLOB_TYPE: &str = "x-ms-blob-type";
 
 /// Azure Storage Blob services support.
 ///
+/// # Capabilities
+///
+/// This service can be used to:
+///
+/// - [x] read
+/// - [x] write
+/// - [x] list
+/// - [ ] presign
+/// - [ ] multipart
+/// - [ ] blocking
+///
 /// # Configuration
 ///
 /// - `root`: Set the work dir for backend.

src/services/azdfs/backend.rs

@@ -40,6 +40,17 @@ use crate::*;
 ///
 /// This service will visist the [ABFS](https://learn.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-abfs-driver) URI supported by [Azure Data Lake Storage Gen2](https://learn.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-introduction).
 ///
+/// # Capabilities
+///
+/// This service can be used to:
+///
+/// - [x] read
+/// - [x] write
+/// - [x] list
+/// - [ ] presign
+/// - [ ] multipart
+/// - [ ] blocking
+///
 /// # Configuration
 ///
 /// - `root`: Set the work dir for backend.

src/services/fs/backend.rs

@@ -34,6 +34,17 @@ use crate::*;
 
 /// POSIX file system support.
 ///
+/// # Capabilities
+///
+/// This service can be used to:
+///
+/// - [x] read
+/// - [x] write
+/// - [x] list
+/// - [ ] ~~presign~~
+/// - [ ] ~~multipart~~
+/// - [x] blocking
+///
 /// # Configuration
 ///
 /// - `root`: Set the work dir for backend.