You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2024/01/02 10:35:15 UTC
(incubator-opendal) branch polish-docs created (now 440696e5a2)
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a change to branch polish-docs
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
at 440696e5a2 docs: Polish core's quick start
This branch includes the following new commits:
new 440696e5a2 docs: Polish core's quick start
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(incubator-opendal) 01/01: docs: Polish core's quick start
Posted by xu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch polish-docs
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit 440696e5a2864dc1f70edfc7c32005cc9b36a36a
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Tue Jan 2 18:34:59 2024 +0800
docs: Polish core's quick start
Signed-off-by: Xuanwo <gi...@xuanwo.io>
---
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(())
//! }