docs: Add OpenDAL VISION

.asf.yaml

@@ -17,7 +17,7 @@
 
 # NOTE: All configurations could be found here: https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features
 github:
-  description: "Apache OpenDAL: Access data freely, painlessly, and efficiently."
+  description: "Apache OpenDAL: access data freely."
   homepage: https://opendal.apache.org
   labels:
     - rust

bindings/c/build.rs

@@ -17,12 +17,20 @@
 
 extern crate cbindgen;
 
-use std::path::Path;
+use std::{path::Path, process::Command};
 
 fn main() {
     let header_file = Path::new("include").join("opendal.h");
 
     cbindgen::generate(".")
         .expect("Unable to generate bindings")
         .write_to_file(header_file);
+
+    Command::new("clang-format")
+        .arg("--style=WebKit")
+        .arg("--verbose")
+        .arg("-i")
+        .arg("include/opendal.h")
+        .spawn()
+        .expect("clang-format must succeed");
 }

bindings/c/include/opendal.h

@@ -65,8 +65,7 @@ typedef enum opendal_code {
      */
     OPENDAL_NOT_A_DIRECTORY,
     /*
-     The given path already exists thus we failed to the specified operation on
-     it.
+     The given path already exists thus we failed to the specified operation on it.
      */
     OPENDAL_ALREADY_EXISTS,
     /*
@@ -160,17 +159,15 @@ extern "C" {
 #endif // __cplusplus
 
 /*
- Returns a result type [`opendal_result_op`], with operator_ptr. If the
- construction succeeds the error is nullptr, otherwise it contains the error
- information.
+ Returns a result type [`opendal_result_op`], with operator_ptr. If the construction succeeds
+ the error is nullptr, otherwise it contains the error information.
 
  # Safety
 
  It is [safe] under two cases below
- * The memory pointed to by `scheme` must contain a valid nul terminator at the
- end of the string.
- * The `scheme` points to NULL, this function simply returns you a null
- opendal_operator_ptr
+ * The memory pointed to by `scheme` must contain a valid nul terminator at the end of
+   the string.
+ * The `scheme` points to NULL, this function simply returns you a null opendal_operator_ptr
  */
 opendal_operator_ptr opendal_operator_new(const char* scheme);
 
@@ -180,14 +177,14 @@ opendal_operator_ptr opendal_operator_new(const char* scheme);
 void opendal_operator_free(opendal_operator_ptr op_ptr);
 
 /*
- Write the data into the path blockingly by operator, returns the error code
- OPENDAL_OK if succeeds, others otherwise
+ Write the data into the path blockingly by operator, returns the error code OPENDAL_OK
+ if succeeds, others otherwise
 
  # Safety
 
  It is [safe] under two cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the
- end of the string.
+ * The memory pointed to by `path` must contain a valid nul terminator at the end of
+   the string.
 
  # Panic
 
@@ -205,15 +202,15 @@ enum opendal_code opendal_operator_blocking_write(opendal_operator_ptr op_ptr,
  # Safety
 
  It is [safe] under two cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the
- end of the string.
+ * The memory pointed to by `path` must contain a valid nul terminator at the end of
+   the string.
 
  # Panic
 
  * If the `path` points to NULL, this function panics
  */
-struct opendal_result_read opendal_operator_blocking_read(
-    opendal_operator_ptr op_ptr, const char* path);
+struct opendal_result_read opendal_operator_blocking_read(opendal_operator_ptr op_ptr,
+    const char* path);
 
 /*
  Check whether the path exists.
@@ -226,15 +223,15 @@ struct opendal_result_read opendal_operator_blocking_read(
  # Safety
 
  It is [safe] under two cases below
- * The memory pointed to by `path` must contain a valid nul terminator at the
- end of the string.
+ * The memory pointed to by `path` must contain a valid nul terminator at the end of
+   the string.
 
  # Panic
 
  * If the `path` points to NULL, this function panics
  */
-struct opendal_result_is_exist opendal_operator_is_exist(
-    opendal_operator_ptr op_ptr, const char* path);
+struct opendal_result_is_exist opendal_operator_is_exist(opendal_operator_ptr op_ptr,
+    const char* path);
 
 /*
  Frees the heap memory used by the [`opendal_bytes`]

core/README.md

@@ -8,7 +8,7 @@
 [chat]: https://img.shields.io/discord/1081052318650339399
 [discord]: https://discord.gg/XQy8yGR2dg
 
-**Open** **D**ata **A**ccess **L**ayer: Access data freely, painlessly, and efficiently
+**Open** **D**ata **A**ccess **L**ayer: access data freely.
 
 - Documentation: [stable](https://docs.rs/opendal/) | [main](https://opendal.apache.org/docs/rust/opendal/)
 - [Release notes](https://docs.rs/opendal/latest/opendal/docs/changelog/index.html)

core/src/lib.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! OpenDAL is the Open Data Access Layer to **freely**, **painlessly**, and **efficiently** access data.
+//! OpenDAL is the Open Data Access Layer to **freely** access data.
 //!
 //! - Documentation: All docs are carried byself, visit [`docs`] for more.
 //! - Services: All supported services could be found at [`services`].

website/docs/index.md

@@ -0,0 +1,76 @@
+---
+title: Overview
+sidebar_position: 1
+---
+
+**Open** **D**ata **A**ccess **L**ayer: Access data freely.
+
+![](https://user-images.githubusercontent.com/5351546/222356748-14276998-501b-4d2a-9b09-b8cff3018204.png)
+
+## Quickstart
+
+### Rust
+
+```rust
+use opendal::Result;
+use opendal::layers::LoggingLayer;
+use opendal::services;
+use opendal::Operator;
+
+#[tokio::main]
+async 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)?
+        // Init with logging layer enabled.
+        .layer(LoggingLayer::default())
+        .finish();
+
+    // Write data
+    op.write("hello.txt", "Hello, World!").await?;
+
+    // Read data
+    let bs = op.read("hello.txt").await?;
+
+    // Fetch metadata
+    let meta = op.stat("hello.txt").await?;
+    let mode = meta.mode();
+    let length = meta.content_length();
+
+    // Delete
+    op.delete("hello.txt").await?;
+
+    Ok(())
+}
+```
+
+### Python
+
+```python
+import asyncio
+
+async def main():
+    op = opendal.AsyncOperator("fs", root="/tmp")
+    await op.write("test.txt", b"Hello World")
+    print(await op.read("test.txt"))
+
+asyncio.run(main())
+```
+
+### Node.js
+
+```js
+import { Operator } from "opendal";
+
+async function main() {
+  const op = new Operator("fs", { root: "/tmp" });
+  await op.write("test", "Hello, World!");
+  const bs = await op.read("test");
+  console.log(new TextDecoder().decode(bs));
+  const meta = await op.stat("test");
+  console.log(`contentLength: ${meta.contentLength}`);
+}
+```

website/sidebars.js → website/docs/sidebars.js

@@ -17,36 +17,11 @@
  * under the License.
  */
 
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
-
 // @ts-check
 
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
-
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
-   */
+  docs: [{ type: 'autogenerated', dirName: '.' }],
 };
 
 module.exports = sidebars;

website/docs/vision.md

@@ -0,0 +1,54 @@
+---
+title: Vision
+sidebar_position: 2
+---
+
+OpenDAL VISION: **access data freely**.
+
+### Free from services
+
+OpenDAL must enable users to access various storage services ranging from `s3` to `dropbox` via it's own native API. It should provide a unified API for accessing all these services.
+
+- Add support for google drive: Good, it allows users to access and manage their data on the google drive.
+- Add support for oss via native API: Good, users can utilize Aliyun's RAM support.
+- Add support for [supabase storage](https://supabase.com/docs/guides/storage): Good, users can visit supabase storage now!
+
+
+- Add support for gcs via XML API: Bad, gcs has native JSON API which more powerful
+- Add support for MySQL/PostgreSQL: Bad, relational DBMS provides data types such as BLOB, but they are often not used as a storage service.
+
+### Free from implementations
+
+OpenDAL needs to separate the various implementation details of services and enables users to write identical logic for different services.
+
+- Add a new capability to indicate whether or not `presign` is supported: Good, users can now write logic based on the `can_presign` option.
+- Add a `default_storage_class` configuration for the S3 service: Good, configuration is specific to the s3 service.
+- Add an option for `content_type` in the `write` operation: Good, it aligns with HTTP standards.
+
+
+- Add a new option in read for `storage_class`: Bad, as different services could have varying values for this parameter.
+
+### Free to integrate
+
+OpenDAL needs to be integrated with different systems.
+
+- Add python binding: Good, users from `python` can use OpenDAL.
+- Add object_store integration: Good, users of `object_store` can adopt OpenDAL.
+
+
+- Rewrite OpenDAL in Golang: Good idea itself, but not related to OpenDAL.
+
+### Free to zero cost
+
+OpenDAL needs to implement features in zero cost way which means:
+
+- Users don't need to pay cost for not used features.
+- Users can't write better implementation for used features.
+
+For examples:
+
+- Add `layer` support: Good, users can add logging/metrics/tracing in zero cost way.
+- Implement `seek` for Reader: Good, users can't write better `seek` support, they all need to pay the same cost.
+
+
+- Add `Arc` for metadata: Bad, users may only need to use metadata once and never clone it. For those who do want this feature, they can add `Arc` themselves

website/docusaurus.config.js

@@ -50,7 +50,7 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: require.resolve('./docs/sidebars.js'),
           editUrl:
             'https://github.com/apache/incubator-opendal/website/',
           showLastUpdateAuthor: true,
@@ -90,6 +90,10 @@ const config = {
             position: 'right',
             label: 'Documentation',
             items: [
+              {
+                type: 'html',
+                value: '<a class="dropdown__link" href="/docs">General</a>'
+              },
               {
                 type: 'html',
                 value: '<a class="dropdown__link" href="/docs/rust/opendal">Rust</a>'