This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 5e49661b04 docs: Polish core's quick start (#3896)
5e49661b04 is described below
commit 5e49661b04f3c7c384494ca02973aef05602f644
Author: Xuanwo <[email protected]>
AuthorDate: Tue Jan 2 18:44:34 2024 +0800
docs: Polish core's quick start (#3896)
Signed-off-by: Xuanwo <[email protected]>
---
core/src/docs/features.md | 28 ---------------
core/src/docs/mod.rs | 6 ----
core/src/lib.rs | 89 +++++++++++++++++++++++++++++++++++++++--------
3 files changed, 75 insertions(+), 48 deletions(-)
diff --git a/core/src/docs/features.md b/core/src/docs/features.md
deleted file mode 100644
index 4777e5f115..0000000000
--- 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 bb11b08551..4da07dd00b 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 50eadc4666..26dfdcd039 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(())
//! }
