Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add docs on website for GHAC service #3296

Merged
merged 1 commit into from
Oct 16, 2023
Merged

docs: Add docs on website for GHAC service #3296

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 1 addition & 85 deletions core/src/services/ghac/backend.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,91 +81,7 @@ fn value_or_env(
}

/// GitHub Action Cache Services support.
///
/// # Capabilities
///
/// This service can be used to:
///
/// - [x] stat
/// - [x] read
/// - [x] write
/// - [x] create_dir
/// - [x] delete
/// - [x] copy
/// - [ ] rename
/// - [ ] list
/// - [ ] scan
/// - [ ] presign
/// - [ ] blocking
/// # Notes
///
/// This service is mainly provided by github actions.
///
/// Refer to [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) for more information.
///
/// To make this service work as expected, please make sure to either call `endpoint` and `token` to
/// configure the URL and credentials, or that the following environment has been setup correctly:
///
/// - `ACTIONS_CACHE_URL`
/// - `ACTIONS_RUNTIME_TOKEN`
///
/// They can be exposed by following action:
///
/// ```yaml
/// - name: Configure Cache Env
/// uses: actions/github-script@v6
/// with:
/// script: |
/// core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
/// core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
/// ```
///
/// To make `delete` work as expected, `GITHUB_TOKEN` should also be set via:
///
/// ```yaml
/// env:
/// GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
/// ```
///
/// # Limitations
///
/// Unlike other services, ghac doesn't support create empty files.
/// We provide a `enable_create_simulation()` to support this operation but may result unexpected side effects.
///
/// Also, `ghac` is a cache service which means the data store inside could
/// be automatically evicted at any time.
///
/// # Configuration
///
/// - `root`: Set the work dir for backend.
///
/// Refer to [`GhacBuilder`]'s public API docs for more information.
///
/// # Example
///
/// ## Via Builder
///
/// ```no_run
/// use std::sync::Arc;
///
/// use anyhow::Result;
/// use opendal::services::Ghac;
/// use opendal::Operator;
///
/// #[tokio::main]
/// async fn main() -> Result<()> {
/// // Create ghac backend builder.
/// let mut builder = Ghac::default();
/// // Set the root for ghac, all operations will happen under this root.
/// //
/// // NOTE: the root must be absolute path.
/// builder.root("/path/to/dir");
///
/// let op: Operator = Operator::new(builder)?.finish();
///
/// Ok(())
/// }
/// ```
#[doc = include_str!("docs.md")]
#[derive(Debug, Default)]
pub struct GhacBuilder {
root: Option<String>,
Expand Down
85 changes: 85 additions & 0 deletions core/src/services/ghac/docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
## Capabilities

This service can be used to:

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

## Notes

This service is mainly provided by github actions.

Refer to [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) for more information.

To make this service work as expected, please make sure to either call `endpoint` and `token` to
configure the URL and credentials, or that the following environment has been setup correctly:

- `ACTIONS_CACHE_URL`
- `ACTIONS_RUNTIME_TOKEN`

They can be exposed by following action:

```yaml
- name: Configure Cache Env
uses: actions/github-script@v6
with:
script: |
core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
```

To make `delete` work as expected, `GITHUB_TOKEN` should also be set via:

```yaml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Limitations

Unlike other services, ghac doesn't support create empty files.
We provide a `enable_create_simulation()` to support this operation but may result unexpected side effects.

Also, `ghac` is a cache service which means the data store inside could
be automatically evicted at any time.

## Configuration

- `root`: Set the work dir for backend.

Refer to [`GhacBuilder`]'s public API docs for more information.

## Example

### Via Builder

```no_run
use std::sync::Arc;

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

#[tokio::main]
async fn main() -> Result<()> {
// Create ghac backend builder.
let mut builder = Ghac::default();
// Set the root for ghac, all operations will happen under this root.
//
// NOTE: the root must be absolute path.
builder.root("/path/to/dir");

let op: Operator = Operator::new(builder)?.finish();

Ok(())
}
```
60 changes: 60 additions & 0 deletions website/docs/services/ghac.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
title: GHAC
---

[GitHub Action Cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) service support

import Docs from '../../../core/src/services/ghac/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 anyhow::Result;
use opendal::services::Ghac;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {

let mut map = HashMap::new();
map.insert("root".to_string(), "/path/to/dir".to_string());

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

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

```javascript
import { Operator } from require('opendal');

async function main() {
const op = new Operator("ghac", {
root: '/path/to/dir'
});
}
```

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

```python
import opendal

op = opendal.Operator("ghac", {
"root": "/path/to/dir"
})
```

</TabItem>
</Tabs>