From 440696e5a2864dc1f70edfc7c32005cc9b36a36a Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Tue, 2 Jan 2024 18:34:59 +0800 Subject: [PATCH] docs: Polish core's quick start Signed-off-by: Xuanwo --- core/src/docs/features.md | 28 ------------ core/src/docs/mod.rs | 6 --- core/src/lib.rs | 89 +++++++++++++++++++++++++++++++++------ 3 files changed, 75 insertions(+), 48 deletions(-) delete mode 100644 core/src/docs/features.md diff --git a/core/src/docs/features.md b/core/src/docs/features.md deleted file mode 100644 index 4777e5f1158..00000000000 --- a/core/src/docs/features.md +++ /dev/null @@ -1,28 +0,0 @@ -## Layer Features - -- `layers-all`: Enable all layers support. -- `layers-metrics`: Enable metrics layer support. -- `layers-prometheus`: Enable prometheus layer support. -- `layers-tracing`: Enable tracing layer support. -- `layers-chaos`: Enable chaos layer support. - -## Service Features - -- `services-dashmap`: Enable dashmap service support. -- `services-ftp`: Enable ftp service support. -- `services-hdfs`: Enable hdfs service support. -- `services-memcached`: Enable memcached service support. -- `services-mini-moka`: Enable mini-moka service support. -- `services-moka`: Enable moka service support. -- `services-ipfs`: Enable ipfs service support. -- `services-redis`: Enable redis service support without TLS. -- `services-redis-native-tls`: Enable redis service support with `native-tls`. -- `services-rocksdb`: Enable rocksdb service support. -- `services-atomicserver`: Enable atomicserver service support. -- `services-sled`: Enable sled service support. - -## Dependencies Features - -- `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` diff --git a/core/src/docs/mod.rs b/core/src/docs/mod.rs index bb11b085512..4da07dd00b0 100644 --- a/core/src/docs/mod.rs +++ b/core/src/docs/mod.rs @@ -29,12 +29,6 @@ pub mod internals; #[doc = include_str!("../../CHANGELOG.md")] pub mod changelog {} -/// All features that provided by OpenDAL. -/// -/// default feature: `rustls`, which enable rustls support. -#[doc = include_str!("features.md")] -pub mod features {} - #[cfg(not(doctest))] pub mod rfcs; diff --git a/core/src/lib.rs b/core/src/lib.rs index 50eadc46664..26dfdcd0396 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -20,19 +20,53 @@ //! Apache OpenDAL™ is a data access layer that allows users to easily and //! efficiently retrieve data from various storage services in a unified way. //! -//! - Documentation: All docs are carried by self, 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]. -//! //! # Quick Start //! +//! OpenDAL's API entry points are [`Operator`] and [`BlockingOperator`]. All +//! public APIs are accessible through the operator. To utilize OpenDAL, you +//! need to: +//! +//! - [Init a service](#init-a-service) +//! - [Compose layers](#compose-layers) +//! - [Use operator](#use-operator) +//! +//! ## Init a service +//! +//! The first step is to pick a service and init it with a builder. All supported +//! services could be found at [`services`]. +//! +//! Let's take [`services::S3`] as an example: +//! //! ```no_run -//! use opendal::layers::LoggingLayer; //! use opendal::services; //! use opendal::Operator; //! use opendal::Result; //! +//! fn main() -> Result<()> { +//! // Pick a builder and configure it. +//! let mut builder = services::S3::default(); +//! builder.bucket("test"); +//! +//! // Init an operator +//! let op = Operator::new(builder)?.finish(); +//! Ok(()) +//! } +//! ``` +//! +//! ## Compose layers +//! +//! The next setup is to compose layers. Layers are modules that provide extra +//! features for every operation. All builtin layers could be found at [`layers`]. +//! +//! Let's use [`layers::LoggingLayer`] as an example; this layer adds logging to +//! every operation that OpenDAL performs. +//! +//! ```no_run +//! use opendal::services; +//! use opendal::Operator; +//! use opendal::Result; +//! use opendal::layers::LoggingLayer; +//! //! #[tokio::main] //! async fn main() -> Result<()> { //! // Pick a builder and configure it. @@ -45,19 +79,46 @@ //! .layer(LoggingLayer::default()) //! .finish(); //! -//! // Write data -//! op.write("hello.txt", "Hello, World!").await?; +//! Ok(()) +//! } +//! ``` +//! +//! ## Use operator +//! +//! The final step is to use the operator. OpenDAL supports both async [`Operator`] +//! and blocking [`BlockingOperator`]. Please pick the one that fits your use case. +//! +//! Every Operator API follows the same pattern, take `read` as an example: +//! +//! - `read`: Execute a read operation. +//! - `read_with`: Execute a read operation with additional options, like `range` and `if_match`. +//! - `reader`: Create a reader for streaming data, enabling flexible access. +//! - `reader_with`: Create a reader with advanced options. +//! +//! ```no_run +//! use opendal::services; +//! use opendal::Operator; +//! use opendal::Result; +//! use opendal::layers::LoggingLayer; +//! +//! #[tokio::main] +//! async fn main() -> Result<()> { +//! // Pick a builder and configure it. +//! let mut builder = services::S3::default(); +//! builder.bucket("test"); //! -//! // Read data -//! let bs = op.read("hello.txt").await?; +//! // Init an operator +//! let op = Operator::new(builder)? +//! // Init with logging layer enabled. +//! .layer(LoggingLayer::default()) +//! .finish(); //! -//! // Fetch metadata +//! // Fetch this file's metadata //! let meta = op.stat("hello.txt").await?; -//! let mode = meta.mode(); //! let length = meta.content_length(); //! -//! // Delete -//! op.delete("hello.txt").await?; +//! // Read data from `hello.txt` with range `0..1024`. +//! let bs = op.read_with("hello.txt").range(0..1024).await?; //! //! Ok(()) //! }