Skip to content

Commit

Permalink
docs: Add new docs that available for all languages (#2285)
Browse files Browse the repository at this point in the history 
* docs: Add new docs that available for all languages

Signed-off-by: Xuanwo <github@xuanwo.io>

* Add licenses

Signed-off-by: Xuanwo <github@xuanwo.io>

---------

Signed-off-by: Xuanwo <github@xuanwo.io>
  • Loading branch information
@Xuanwo
Xuanwo committed May 22, 2023
1 parent 958f545 commit 65d1a57
Show file tree
Hide file tree
Showing 5 changed files with 185 additions and 84 deletions.
79 changes: 1 addition & 78 deletions core/src/services/azblob/backend.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,84 +52,7 @@ const AZBLOB_BATCH_LIMIT: usize = 256;

/// Azure Storage Blob services support.
///
/// # Capabilities
///
/// This service can be used to:
///
/// - [x] stat
/// - [x] read
/// - [x] write
/// - [x] create_dir
/// - [x] delete
/// - [x] copy
/// - [ ] rename
/// - [x] list
/// - [x] scan
/// - [x] presign
/// - [ ] blocking
///
/// # Configuration
///
/// - `root`: Set the work dir for backend.
/// - `container`: Set the container name for backend.
/// - `endpoint`: Set the endpoint for backend.
/// - `account_name`: Set the account_name for backend.
/// - `account_key`: Set the account_key for backend.
///
/// Refer to public API docs for more information.
///
/// # Example
///
/// This example works on [Azurite](https://github.com/Azure/Azurite) for local developments.
///
/// ## Start local blob service
///
/// ```shell
/// docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite
/// az storage container create --name test --connection-string "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
/// ```
///
/// ## Init OpenDAL Operator
///
/// ### Via Builder
///
/// ```no_run
/// use std::sync::Arc;
///
/// use anyhow::Result;
/// use opendal::services::Azblob;
/// use opendal::Operator;
///
/// #[tokio::main]
/// async fn main() -> Result<()> {
/// // Create azblob backend builder.
/// let mut builder = Azblob::default();
/// // Set the root for azblob, all operations will happen under this root.
/// //
/// // NOTE: the root must be absolute path.
/// builder.root("/path/to/dir");
/// // Set the container name, this is required.
/// builder.container("test");
/// // Set the endpoint, this is required.
/// //
/// // For examples:
/// // - "http://127.0.0.1:10000/devstoreaccount1"
/// // - "https://accountname.blob.core.windows.net"
/// builder.endpoint("http://127.0.0.1:10000/devstoreaccount1");
/// // Set the account_name and account_key.
/// //
/// // OpenDAL will try load credential from the env.
/// // If credential not set and no valid credential in env, OpenDAL will
/// // send request without signing like anonymous user.
/// builder.account_name("devstoreaccount1");
/// builder.account_key("Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==");
///
/// // `Accessor` provides the low level APIs, we will use `Operator` normally.
/// let op: Operator = Operator::new(builder)?.finish();
///
/// Ok(())
/// }
/// ```
#[doc = include_str!("docs.md")]
#[derive(Default, Clone)]
pub struct AzblobBuilder {
root: Option<String>,
Expand Down
77 changes: 77 additions & 0 deletions core/src/services/azblob/docs.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Capabilities

This service can be used to:

- [x] stat
- [x] read
- [x] write
- [x] create_dir
- [x] delete
- [x] copy
- [ ] rename
- [x] list
- [x] scan
- [x] presign
- [ ] blocking

# Configuration

- `root`: Set the work dir for backend.
- `container`: Set the container name for backend.
- `endpoint`: Set the endpoint for backend.
- `account_name`: Set the account_name for backend.
- `account_key`: Set the account_key for backend.

Refer to public API docs for more information.

# Examples

This example works on [Azurite](https://github.com/Azure/Azurite) for local developments.

## Start local blob service

```shell
docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite
az storage container create --name test --connection-string "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
```

## Init OpenDAL Operator

### Via Builder

```rust
use std::sync::Arc;

use anyhow::Result;
use opendal::services::Azblob;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
// Create azblob backend builder.
let mut builder = Azblob::default();
// Set the root for azblob, all operations will happen under this root.
//
// NOTE: the root must be absolute path.
builder.root("/path/to/dir");
// Set the container name, this is required.
builder.container("test");
// Set the endpoint, this is required.
//
// For examples:
// - "http://127.0.0.1:10000/devstoreaccount1"
// - "https://accountname.blob.core.windows.net"
builder.endpoint("http://127.0.0.1:10000/devstoreaccount1");
// Set the account_name and account_key.
//
// OpenDAL will try load credential from the env.
// If credential not set and no valid credential in env, OpenDAL will
// send request without signing like anonymous user.
builder.account_name("devstoreaccount1");
builder.account_key("Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==");

// `Accessor` provides the low level APIs, we will use `Operator` normally.
let op: Operator = Operator::new(builder)?.finish();
Ok(())
}
```
24 changes: 24 additions & 0 deletions website/docs/services/_category_.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.

position: 3
label: 'Services'
collapsible: true
collapsed: false
link:
type: generated-index
title: Services
73 changes: 73 additions & 0 deletions website/docs/services/azblob.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: Azblob
---

Azure Storage Blob services support.

import Docs from '../../../core/src/services/azblob/docs.md'

<Docs components={props.components} />

### Via Config

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="rust" label="Rust" default>

```rust
use std::sync::Arc;

use anyhow::Result;
use opendal::services::Azblob;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
let mut map = HashMap::new();
map.insert("root".to_string(), "/path/to/dir".to_string());
map.insert("container".to_string(), "test".to_string());
map.insert("endpoint".to_string(), "http://127.0.0.1:10000/devstoreaccount1".to_string());
map.insert("account_name".to_string(), "devstoreaccount1".to_string());
map.insert("account_key".to_string(), "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==".to_string());

let op: Operator = Operator::via_map(Scheme::Azblob, map)?;
Ok(())
}
```

</TabItem>
<TabItem value="node.js" label="Node.js">

```javascript
import { Operator } from "opendal";

async function main() {
const op = new Operator("azblob", {
root: "/path/to/dir",
container: "test",
endpoint: "http://127.0.0.1:10000/devstoreaccount1",
account_name: "devstoreaccount1",
account_key: "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==",
});
}
```

</TabItem>
<TabItem value="python" label="Python">

```python
import opendal

op = opendal.Operator("azblob",
root="/path/to/dir",
container="test",
endpoint="http://127.0.0.1:10000/devstoreaccount1",
account_name="devstoreaccount1",
account_key="Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==",
)
```

</TabItem>
</Tabs>
16 changes: 10 additions & 6 deletions website/docusaurus.config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ const config = {
alt: 'Apache OpenDAL(incubating)',
src: 'img/logo.svg',
srcDark: 'img/logo_dark.svg',
href: 'https://opendal.apache.org/',
href: '/',
target: '_self',
height: 32,
},
Expand All @@ -98,20 +98,24 @@ const config = {
label: 'Documentation',
items: [
{
type: 'html',
value: '<a class="dropdown__link" href="/docs">General</a>'
label: 'General',
to: '/docs'
},
{
label: 'Services',
to: '/docs/category/services'
},
{
type: 'html',
value: '<a class="dropdown__link" href="/docs/rust/opendal">Rust</a>'
value: '<a class="dropdown__link" href="/docs/rust/opendal">Rust Core</a>'
},
{
type: 'html',
value: '<a class="dropdown__link" href="/docs/nodejs/">Node.js</a>'
value: '<a class="dropdown__link" href="/docs/nodejs/">Node.js Binding</a>'
},
{
type: 'html',
value: '<a class="dropdown__link" href="/docs/python/">Python</a>'
value: '<a class="dropdown__link" href="/docs/python/">Python Binding</a>'
},
]
},
Expand Down

0 comments on commit 65d1a57

Please sign in to comment.