From 68fdd43e120da956248ab6c80c60cad73ac2b37b Mon Sep 17 00:00:00 2001 From: tison Date: Fri, 29 Sep 2023 11:02:24 +0800 Subject: [PATCH] docs: add multilingual getting started (#3214) * docs: rework the download page Signed-off-by: tison * docs: by default collapse services Signed-off-by: tison * docs: separate API docs Signed-off-by: tison * docs: add multilingual getting started Signed-off-by: tison --------- 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 | 4 +- website/docs/vision.md | 2 +- website/docusaurus.config.js | 8 +- website/src/pages/download.md | 45 +++--- 7 files changed, 215 insertions(+), 96 deletions(-) create mode 100644 website/docs/getting-started.md diff --git a/website/docs/contributing/_category_.yml b/website/docs/contributing/_category_.yml index b5c31ea4915..981dc164182 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 00000000000..0feb7304756 --- /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 04c6277c29d..a383a403a14 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 2323f7be464..4c79c1c6d4b 100644 --- a/website/docs/services/_category_.yml +++ b/website/docs/services/_category_.yml @@ -15,10 +15,10 @@ # specific language governing permissions and limitations # under the License. -position: 3 +position: 4 label: 'Services' collapsible: true -collapsed: false +collapsed: true link: type: generated-index title: Services diff --git a/website/docs/vision.md b/website/docs/vision.md index ad5191e6e55..2323e6235f7 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**. --- diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 71e3431ef5e..86b50f54eae 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/' diff --git a/website/src/pages/download.md b/website/src/pages/download.md index b19680121e0..69f26e7fed8 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 ```