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 640a7d23 docs: Add OpenDAL VISION (#2007)
640a7d23 is described below
commit 640a7d23b67f6b7988112b6fb75d4d53b6790840
Author: Xuanwo <[email protected]>
AuthorDate: Sun Apr 16 18:38:46 2023 +0800
docs: Add OpenDAL VISION (#2007)
* docs: Add OpenDAL VISION
Signed-off-by: Xuanwo <[email protected]>
* Format c binding
Signed-off-by: Xuanwo <[email protected]>
* Make sure binding been formated
Signed-off-by: Xuanwo <[email protected]>
* FIx docs
Signed-off-by: Xuanwo <[email protected]>
* polish
Signed-off-by: Xuanwo <[email protected]>
---------
Signed-off-by: Xuanwo <[email protected]>
---
.asf.yaml | 2 +-
bindings/c/build.rs | 10 +++++-
bindings/c/include/opendal.h | 39 ++++++++++------------
core/README.md | 2 +-
core/src/lib.rs | 2 +-
website/docs/index.md | 76 ++++++++++++++++++++++++++++++++++++++++++
website/docs/overview.md | 4 ---
website/{ => docs}/sidebars.js | 27 +--------------
website/docs/vision.md | 61 +++++++++++++++++++++++++++++++++
website/docusaurus.config.js | 6 +++-
10 files changed, 173 insertions(+), 56 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index c6ff7d55..730f0b35 100644
--- a/.asf.yaml
+++ b/.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
diff --git a/bindings/c/build.rs b/bindings/c/build.rs
index 47b27812..e5b01158 100644
--- a/bindings/c/build.rs
+++ b/bindings/c/build.rs
@@ -17,7 +17,7 @@
extern crate cbindgen;
-use std::path::Path;
+use std::{path::Path, process::Command};
fn main() {
let header_file = Path::new("include").join("opendal.h");
@@ -25,4 +25,12 @@ fn main() {
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");
}
diff --git a/bindings/c/include/opendal.h b/bindings/c/include/opendal.h
index e177cb71..21d9ba4e 100644
--- a/bindings/c/include/opendal.h
+++ b/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`]
diff --git a/core/README.md b/core/README.md
index 7640e64e..8bbce48e 100644
--- a/core/README.md
+++ b/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)
diff --git a/core/src/lib.rs b/core/src/lib.rs
index b5df5aea..bc361738 100644
--- a/core/src/lib.rs
+++ b/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`].
diff --git a/website/docs/index.md b/website/docs/index.md
new file mode 100644
index 00000000..2d4a3295
--- /dev/null
+++ b/website/docs/index.md
@@ -0,0 +1,76 @@
+---
+title: Overview
+sidebar_position: 1
+---
+
+**Open** **D**ata **A**ccess **L**ayer: Access data freely.
+
+
+
+## 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}`);
+}
+```
diff --git a/website/docs/overview.md b/website/docs/overview.md
deleted file mode 100644
index 42956286..00000000
--- a/website/docs/overview.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-sidebar_position: 1
-title: Overview
----
diff --git a/website/sidebars.js b/website/docs/sidebars.js
similarity index 59%
rename from website/sidebars.js
rename to website/docs/sidebars.js
index 850844c2..7704508a 100644
--- a/website/sidebars.js
+++ b/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;
diff --git a/website/docs/vision.md b/website/docs/vision.md
new file mode 100644
index 00000000..dab6e36e
--- /dev/null
+++ b/website/docs/vision.md
@@ -0,0 +1,61 @@
+---
+title: Vision
+sidebar_position: 2
+---
+
+OpenDAL VISION is: **access data freely**.
+
+---
+
+This is an overview of what the shape of OpenDAL looks like, but also somewhat
zoomed out, so that the vision can survive while the exact minute details might
shift and change over time.
+
+## 1. 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.
+
+### Examples
+
+- Add support for [Google Drive](https://www.google.com/drive/): Good, it
allows users to access and manage their data on the [Google
Drive](https://www.google.com/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](https://cloud.google.com/storage) via [XML
API](https://cloud.google.com/storage/docs/xml-api/overview): Bad,
[GCS](https://cloud.google.com/storage) has native [JSON
API](https://cloud.google.com/storage/docs/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.
+
+## 2. Free from implementations
+
+OpenDAL needs to separate the various implementation details of services and
enables users to write identical logic for different services.
+
+### Examples
+
+- 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.
+
+## 3. Free to integrate
+
+OpenDAL needs to be integrated with different systems.
+
+### Examples
+
+- Add python binding: Good, users from `python` can use OpenDAL.
+- Add object_store integration: Good, users of `object_store` can adopt
OpenDAL.
+
+## 4. 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.
+
+### 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
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 29eb75b3..680abdb2 100644
--- a/website/docusaurus.config.js
+++ b/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>'
