docs: add rust usage example (#2447)

* add rust usage example

* separate into different folders

* fix CI error

* make it to section01

* update

* update

Cargo.toml

@@ -20,6 +20,7 @@ debug = true
 
 [workspace]
 default-members = ["core"]
+exclude = ["examples"]
 members = [
   "core",
 

README.md

@@ -98,7 +98,7 @@ Major components of the project include:
 
 ## Documentation
 
-The documentation is available at <https://opendal.apache.org>.
+The documentation is available at <https://opendal.apache.org>. Checkout [here](./examples/) for the usage examples(still working on).
 
 We are engaged in a practice we call "documentation as code". You can also view the documentation directly in project's source code. And we welcome you to contribute to the documentation.
 

examples/rust/section01-introduction/.gitignore

@@ -0,0 +1,2 @@
+/target
+/tmp

examples/rust/section01-introduction/Cargo.toml

@@ -0,0 +1,29 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[package]
+name = "section01-introduction"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+opendal = { version = "0.37.0" }
+tokio = { version = "1.27", features = ["full"] }
+anyhow = { version = "1.0.30", features = ["std"] }
+futures = { version = "0.3" }

examples/rust/section01-introduction/README.md

@@ -0,0 +1,49 @@
+# Introduction
+
+Rust is a systems programming language that is known for its performance, memory safety, and concurrency features. OpenDAL(**Open D**ata **A**ccess **L**ayer) is a Rust project to access data freely, painlessly and efficiently.
+
+This examples documentation is organized in a progressive manner, with each section building upon the previous one. Each section is located in a different folder and contains both documentation and a stand-alone project that can be run independently.
+
+The following will briefly introduce dev environment set up, the Rust project structure, some important files, and how to quickly create a project. This is prepared for those who are not familiar with Rust. If you are familiar with Rust, you can skip this section.
+
+
+# Environment set up
+
+There need rust toolchain in your local environment, if you haven't set it up, you can refer [here](https://github.com/apache/incubator-opendal/blob/main/CONTRIBUTING.md#bring-your-own-toolbox) to figure it out.
+
+
+# Rust Project Structure
+
+A typical Rust project follows a specific directory structure. Here's an overview of the main directories and files you'll encounter in a Rust project:
+
+- src/: This directory contains the source code for your Rust project. It typically includes a main.rs file, which is the entry point for your application.
+
+- Cargo.toml: This file contains metadata about your project, such as its name, version, and dependencies. It also specifies the build configuration for your project.
+
+## Cargo.toml
+
+Cargo is Rust's package manager and build tool. It uses the Cargo.toml file to manage dependencies and build configurations for your project.
+
+Here's an example Cargo.toml file for a Rust project:
+
+```toml
+[package]
+name = "my_project"
+version = "0.1.0"
+authors = ["Your Name <your.email@example.com>"]
+edition = "2018"
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+```
+## main.rs
+The main.rs file is the entry point for your Rust application. It typically contains the `main()` function, which is the starting point for your program.
+
+
+# Basic Usage
+
+In this section, we chose `Fs` service as example because it is simple and don't need extra work to set up, all service available can be found [here](https://docs.rs/opendal/latest/opendal/services/index.html).
+
+This is a independent project, the `src/main.rs` provide a example usage about `Fs`. It `read` a file and print its content to console, overwrite some new content to it and read & print content again to verify the `write` operator has been taken effect and then delete the file.
+
+Use `cargo run` to run this project. Just take a try.

examples/rust/section01-introduction/src/main.rs

@@ -0,0 +1,58 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use opendal::Operator;
+use opendal::Result;
+use opendal::services::Fs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+
+    // Create fs backend builder.
+    let mut builder = Fs::default();
+
+    // set the root to `section01-introduction/tmp`, all operations will happen under this root.
+    // note that the root must be absolute path.
+    let mut path = std::env::current_dir().unwrap();
+    path.push("tmp");
+    builder.root(path.to_str().unwrap());
+
+    // create an `Operator` from `builder`, all file operations are initiated from it.
+    let op: Operator = Operator::new(builder)?.finish();
+
+    // if the 'root' path haven't been set, then the `file_path` below should be `section01-introduction/tmp/1.txt`.
+    let file_path = "1.txt";
+    op.write(file_path, "This is OpenDAL usage documentation section01-introduction.").await?;
+
+    // read the file and print its content.
+    let read_file = op.read(file_path).await?;
+    let content = String::from_utf8(read_file).unwrap();
+    println!("{}", content);
+
+    // write the file.
+    op.write(file_path, "File content has been overwrite.").await?;
+
+    // verify the file content after the write operator.
+    let read_file = op.read(file_path).await?;
+    let content = String::from_utf8(read_file).unwrap();
+    println!("{}", content);
+
+    // delete the file.
+    op.delete(file_path).await?;
+
+    Ok(())
+}