From 8004f50051983a0105ff69b647df3608975cacca Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 29 Sep 2023 10:20:18 +0800 Subject: [PATCH 1/4] docs: rework the download page Signed-off-by: tison --- website/src/pages/download.md | 45 +++++++++++++++++------------------ 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/website/src/pages/download.md b/website/src/pages/download.md index b19680121e05..69f26e7fed8e 100644 --- a/website/src/pages/download.md +++ b/website/src/pages/download.md @@ -1,13 +1,10 @@ --- title: Download --- -# Download - -
-# Apache OpenDAL(incubating) Downloads +# Download -Apache OpenDAL(incubating) is released as a source artifact. +The official Apache OpenDAL (incubating) releases are as source artifacts. ## Releases @@ -22,31 +19,33 @@ Apache OpenDAL(incubating) is released as a source artifact. For older releases, please check the [archive](https://dlcdn.apache.org/incubator/opendal/). -### Notes -- When downloading a release, please check the SHA-512 and verify the OpenPGP compatible signature from the main Apache site. Links are provided above (next to the release download link). +## Notes -- The KEYS file contains the public keys used for signing release. It is recommended that (when possible) a web of trust is used to confirm the identity of these keys. - -- Please download the [KEYS](https://dlcdn.apache.org/incubator/opendal/KEYS) as well as the .asc signature files. +* When downloading a release, please check the SHA-512 and verify the OpenPGP compatible signature from the main Apache site. Links are provided above (next to the release download link). +* The KEYS file contains the public keys used for signing release. It is recommended that (when possible) a web of trust is used to confirm the identity of these keys. +* Please download the [KEYS](https://downloads.apache.org/incubator/opendal/KEYS) as well as the .asc signature files. ### To verify the signature of the release artifact -You will need to download both the release artifact and the .asc signature file for that artifact. Then verify the signature using: +You will need to download both the release artifact and the .asc signature file for that artifact. Then verify the signature by: -- Download the KEYS file and the .asc signature files for the relevant release artifacts. -- Import the KEYS file to your GPG keyring: -``` -$ gpg --import KEYS -``` -- Verify the signature of the release artifact using the following command: -``` -$ gpg --verify .asc -``` +* Download the KEYS file and the .asc signature files for the relevant release artifacts. +* Import the KEYS file to your GPG keyring: + + ```shell + gpg --import KEYS + ``` + +* Verify the signature of the release artifact using the following command: + + ```shell + gpg --verify .asc + ``` ### To verify the checksum of the release artifact -You will need to download both the release artifact and the .sha512 checksum file for that artifact. Then verify the checksum using: +You will need to download both the release artifact and the .sha512 checksum file for that artifact. Then verify the checksum by: -``` -$ shasum -a 512 -c .sha512 +```shell +shasum -a 512 -c .sha512 ``` From 5f20dcb782a551ecbe22e29b01c0073e90642692 Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 29 Sep 2023 10:21:06 +0800 Subject: [PATCH 2/4] docs: by default collapse services Signed-off-by: tison --- website/docs/services/_category_.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/services/_category_.yml b/website/docs/services/_category_.yml index 2323f7be4641..f8861bc8bf69 100644 --- a/website/docs/services/_category_.yml +++ b/website/docs/services/_category_.yml @@ -18,7 +18,7 @@ position: 3 label: 'Services' collapsible: true -collapsed: false +collapsed: true link: type: generated-index title: Services From 05653c81fa3efdc865344dde7094ee75071df280 Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 29 Sep 2023 10:24:00 +0800 Subject: [PATCH 3/4] docs: separate API docs Signed-off-by: tison --- website/docusaurus.config.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 71e3431ef5e9..86b50f54eaeb 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -98,7 +98,7 @@ const config = { label: 'Docs', items: [ { - label: 'General', + label: 'Overview', to: '/docs/overview' }, { @@ -109,6 +109,12 @@ const config = { label: 'Services', to: '/docs/category/services' }, + ] + }, + { + position: 'right', + label: 'API', + items: [ { label: 'Rust Core', to: 'pathname:///docs/rust/opendal/' From cdb574f3a7979d42bdde221f0ebc6eab0d158718 Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 29 Sep 2023 10:56:59 +0800 Subject: [PATCH 4/4] docs: add multilingual getting started Signed-off-by: tison --- website/docs/contributing/_category_.yml | 2 +- website/docs/getting-started.md | 175 +++++++++++++++++++++++ website/docs/overview.md | 75 +--------- website/docs/services/_category_.yml | 2 +- website/docs/vision.md | 2 +- 5 files changed, 185 insertions(+), 71 deletions(-) create mode 100644 website/docs/getting-started.md diff --git a/website/docs/contributing/_category_.yml b/website/docs/contributing/_category_.yml index b5c31ea49153..981dc164182e 100644 --- a/website/docs/contributing/_category_.yml +++ b/website/docs/contributing/_category_.yml @@ -15,7 +15,7 @@ # specific language governing permissions and limitations # under the License. -position: 4 +position: 5 label: 'Contributing' collapsible: true collapsed: true diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md new file mode 100644 index 000000000000..0feb7304756a --- /dev/null +++ b/website/docs/getting-started.md @@ -0,0 +1,175 @@ +--- +title: Getting started +sidebar_position: 3 +--- + +OpenDAL can be easily integrated into different software with its Rust core and multilingual bindings. + +## Rust core + +OpenDAL's core is implemented in Rust programming language. The most convenient way to use OpenDAL in your Rust program add the OpenDAL Cargo crate as a dependency. + +### Install + +Run the following Cargo command in your project directory: + +```shell +cargo add opendal +``` + +Or add the following line to your Cargo.toml: + +```shell +opendal = "0.40.0" +``` + +### Demo + +Try it out: + +```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(()) +} +``` + +## Java binding + +OpenDAL's Java binding is released to Maven central as [`org.apache.opendal:opendal-java:${version}`](https://central.sonatype.com/artifact/org.apache.opendal/opendal-java). + +### Install + +#### Maven + +Generally, you can first add the `os-maven-plugin` for automatically detect the classifier based on your platform: + +```xml + + + + kr.motd.maven + os-maven-plugin + 1.7.0 + + + +``` + +Then add the dependency to opendal-java as following: + +```xml + + + org.apache.opendal + opendal-java + ${opendal.version} + + + org.apache.opendal + opendal-java + ${opendal.version} + ${os.detected.classifier} + + +``` + +#### Gradle + +For Gradle, you can first add the `com.google.osdetector` for automatically detect the classifier based on your platform: + +```groovy +plugins { + id "com.google.osdetector" version "1.7.3" +} +``` + +Then add the dependency to opendal-java as following: + +```groovy +dependencies { + implementation "org.apache.opendal:opendal-java:$opendal.version" + implementation "org.apache.opendal:opendal-java:$opendal.version:$osdetector.classifier" +} +``` + +#### Classified library + +For details in specifying classified library, read the [dedicated explanation](https://github.com/apache/incubator-opendal/tree/main/bindings/java). + +### Demo + +Try it out: + +```java +final Map conf = new HashMap<>(); +final Operator op = Operator.of("memory", conf); +// Write data +op.write("hello.txt", "Hello, World!").join(); +// Read data +final byte[] bs = op.read("hello.txt").join(); +// Delete +op.delete("hello.txt").join(); +``` + +## Python binding + +### Demo + +```python +import opendal +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 binding + +### Demo + +```javascript +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 index 04c6277c29d8..a383a403a140 100644 --- a/website/docs/overview.md +++ b/website/docs/overview.md @@ -1,77 +1,16 @@ --- -title: Overview +title: Welcome to Apache OpenDAL sidebar_position: 1 --- -**Open** **D**ata **A**ccess **L**ayer: Access data freely. +OpenDAL represents **Open** **D**ata **A**ccess **L**ayer. Our vision is to **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?; +## What OpenDAL does? - // 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 opendal -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()) -``` +![](https://user-images.githubusercontent.com/5351546/222356748-14276998-501b-4d2a-9b09-b8cff3018204.png) -### Node.js +See the page for our vision in details: [Vision](vision.md). -```js -import { Operator } from "opendal"; +## Getting started -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}`); -} -``` +See the page for quick start with multiple languages: [Getting started](getting-started.md). diff --git a/website/docs/services/_category_.yml b/website/docs/services/_category_.yml index f8861bc8bf69..4c79c1c6d4ba 100644 --- a/website/docs/services/_category_.yml +++ b/website/docs/services/_category_.yml @@ -15,7 +15,7 @@ # specific language governing permissions and limitations # under the License. -position: 3 +position: 4 label: 'Services' collapsible: true collapsed: true diff --git a/website/docs/vision.md b/website/docs/vision.md index ad5191e6e559..2323e6235f72 100644 --- a/website/docs/vision.md +++ b/website/docs/vision.md @@ -3,7 +3,7 @@ title: Vision sidebar_position: 2 --- -OpenDAL VISION is: **access data freely**. +The VISION of OpenDAL is: **access data freely**. ---