-
Notifications
You must be signed in to change notification settings - Fork 472
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add multilingual getting started (#3214)
* docs: rework the download page Signed-off-by: tison <[email protected]> * docs: by default collapse services Signed-off-by: tison <[email protected]> * docs: separate API docs Signed-off-by: tison <[email protected]> * docs: add multilingual getting started Signed-off-by: tison <[email protected]> --------- Signed-off-by: tison <[email protected]>
- Loading branch information
Showing
7 changed files
with
215 additions
and
96 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| <build> | ||
| <extensions> | ||
| <extension> | ||
| <groupId>kr.motd.maven</groupId> | ||
| <artifactId>os-maven-plugin</artifactId> | ||
| <version>1.7.0</version> | ||
| </extension> | ||
| </extensions> | ||
| </build> | ||
| ``` | ||
|
|
||
| Then add the dependency to opendal-java as following: | ||
|
|
||
| ```xml | ||
| <dependencies> | ||
| <dependency> | ||
| <groupId>org.apache.opendal</groupId> | ||
| <artifactId>opendal-java</artifactId> | ||
| <version>${opendal.version}</version> | ||
| </dependency> | ||
| <dependency> | ||
| <groupId>org.apache.opendal</groupId> | ||
| <artifactId>opendal-java</artifactId> | ||
| <version>${opendal.version}</version> | ||
| <classifier>${os.detected.classifier}</classifier> | ||
| </dependency> | ||
| </dependencies> | ||
| ``` | ||
|
|
||
| #### 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<String, String> 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}`); | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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**. | ||
|
|
||
|  | ||
|
|
||
| ## 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()) | ||
| ``` | ||
|  | ||
|
|
||
| ### 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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters