You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2023/03/16 03:14:52 UTC
[incubator-opendal] branch main updated: feat(bindings/nodejs): Auto-generate docs (#1625)
This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new ee4d2fc4 feat(bindings/nodejs): Auto-generate docs (#1625)
ee4d2fc4 is described below
commit ee4d2fc4d99cfe45039460e87fa5477e024e6f4a
Author: Suyan <su...@gmail.com>
AuthorDate: Thu Mar 16 11:14:48 2023 +0800
feat(bindings/nodejs): Auto-generate docs (#1625)
* feat(bindings/nodejs): auto generate docs
Signed-off-by: suyanhanx <su...@gmail.com>
* chore(bindings/nodejs): remove .cargo
Signed-off-by: suyanhanx <su...@gmail.com>
* docs: add nodejs doc entry to website
Signed-off-by: suyanhanx <su...@gmail.com>
* fix: broken navbar link
Signed-off-by: suyanhanx <su...@gmail.com>
---------
Signed-off-by: suyanhanx <su...@gmail.com>
---
.github/workflows/docs.yml | 24 ++++++++++++-
bindings/nodejs/.gitignore | 1 +
bindings/nodejs/Cargo.toml | 4 ---
bindings/nodejs/package.json | 2 ++
bindings/nodejs/src/lib.rs | 24 +++++++++++++
bindings/nodejs/typedoc.json | 15 ++++++++
bindings/nodejs/yarn.lock | 82 ++++++++++++++++++++++++++++++++++++++++++++
website/docusaurus.config.js | 8 +++--
website/src/pages/index.js | 2 +-
9 files changed, 154 insertions(+), 8 deletions(-)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f971c5c3..51d301e9 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -55,7 +55,7 @@ jobs:
run: |
cp -r ./target/doc ./website/static/docs/rust
- # Build website ---------------------------------------------------
+ # Set node.js environment -----------------------------------------
- uses: actions/setup-node@v3
with:
node-version: '16'
@@ -70,6 +70,28 @@ jobs:
path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+ # Build bindings/nodejs docs --------------------------------------
+ - name: Corepack
+ working-directory: bindings/nodejs
+ run: corepack enable
+
+ - name: Install dependencies
+ working-directory: bindings/nodejs
+ run: yarn install
+
+ - name: Build
+ working-directory: bindings/nodejs
+ run: yarn build
+
+ - name: Build bindings/nodejs Docs
+ working-directory: bindings/nodejs
+ run: yarn docs
+
+ - name: Copy docs into build
+ run: |
+ cp -r ./bindings/nodejs/docs ./website/static/docs/nodejs
+
+ # Build website ---------------------------------------------------
- name: Install Dependencies
working-directory: website
run: |
diff --git a/bindings/nodejs/.gitignore b/bindings/nodejs/.gitignore
index dba49de7..05af5aea 100644
--- a/bindings/nodejs/.gitignore
+++ b/bindings/nodejs/.gitignore
@@ -189,6 +189,7 @@ Cargo.lock
.pnp.*
.yarn
*.node
+docs/
generated*.*
index.d.ts
diff --git a/bindings/nodejs/Cargo.toml b/bindings/nodejs/Cargo.toml
index c0f572a9..f20669fe 100644
--- a/bindings/nodejs/Cargo.toml
+++ b/bindings/nodejs/Cargo.toml
@@ -35,7 +35,3 @@ time = { version = "0.3.17", features = ["formatting"] }
[build-dependencies]
napi-build = "2"
-
-[target.aarch64-unknown-linux-musl]
-linker = "aarch64-linux-musl-gcc"
-rustflags = ["-C", "target-feature=-crt-static"]
diff --git a/bindings/nodejs/package.json b/bindings/nodejs/package.json
index 7215ea9f..673459df 100644
--- a/bindings/nodejs/package.json
+++ b/bindings/nodejs/package.json
@@ -37,6 +37,7 @@
"@swc/core": "^1.3.38",
"@types/node": "^18.14.5",
"ava": "^5.2.0",
+ "typedoc": "^0.23.26",
"typescript": "^4.9.5"
},
"ava": {
@@ -59,6 +60,7 @@
"artifacts": "napi artifacts",
"build": "napi build --platform --release --js generated.js --js-package-name @opendal/lib",
"build:debug": "napi build --platform --js generated.js --js-package-name @opendal/lib",
+ "docs": "typedoc",
"prepublishOnly": "napi prepublish -t npm",
"test": "ava",
"version": "napi version"
diff --git a/bindings/nodejs/src/lib.rs b/bindings/nodejs/src/lib.rs
index 27ceef31..ea7016c8 100644
--- a/bindings/nodejs/src/lib.rs
+++ b/bindings/nodejs/src/lib.rs
@@ -100,6 +100,7 @@ impl Operator {
build_operator(scheme, options).map(Operator)
}
+ /// Get current path's metadata **without cache** directly.
#[napi]
pub async fn stat(&self, path: String) -> Result<Metadata> {
let meta = self.0.stat(&path).await.map_err(format_napi_error)?;
@@ -107,6 +108,7 @@ impl Operator {
Ok(Metadata(meta))
}
+ /// Get current path's metadata **without cache** directly and synchronously.
#[napi]
pub fn stat_sync(&self, path: String) -> Result<Metadata> {
let meta = self.0.blocking().stat(&path).map_err(format_napi_error)?;
@@ -114,11 +116,13 @@ impl Operator {
Ok(Metadata(meta))
}
+ /// Create dir with given path.
#[napi]
pub async fn create_dir(&self, path: String) -> Result<()> {
self.0.create_dir(&path).await.map_err(format_napi_error)
}
+ /// Create dir with given path synchronously.
#[napi]
pub fn create_dir_sync(&self, path: String) -> Result<()> {
self.0
@@ -127,35 +131,41 @@ impl Operator {
.map_err(format_napi_error)
}
+ /// Write bytes into path.
#[napi]
pub async fn write(&self, path: String, content: Either<Buffer, String>) -> Result<()> {
let c = content.as_ref().to_owned();
self.0.write(&path, c).await.map_err(format_napi_error)
}
+ /// Write bytes into path synchronously.
#[napi]
pub fn write_sync(&self, path: String, content: Either<Buffer, String>) -> Result<()> {
let c = content.as_ref().to_owned();
self.0.blocking().write(&path, c).map_err(format_napi_error)
}
+ /// Read the whole path into a buffer.
#[napi]
pub async fn read(&self, path: String) -> Result<Buffer> {
let res = self.0.read(&path).await.map_err(format_napi_error)?;
Ok(res.into())
}
+ /// Read the whole path into a buffer synchronously.
#[napi]
pub fn read_sync(&self, path: String) -> Result<Buffer> {
let res = self.0.blocking().read(&path).map_err(format_napi_error)?;
Ok(res.into())
}
+ /// List dir in flat way.
#[napi]
pub async fn scan(&self, path: String) -> Result<Lister> {
Ok(Lister(self.0.scan(&path).await.map_err(format_napi_error)?))
}
+ /// List dir in flat way synchronously.
#[napi]
pub fn scan_sync(&self, path: String) -> Result<BlockingLister> {
Ok(BlockingLister(
@@ -163,21 +173,34 @@ impl Operator {
))
}
+ /// Delete the given path.
#[napi]
pub async fn delete(&self, path: String) -> Result<()> {
self.0.delete(&path).await.map_err(format_napi_error)
}
+ /// Delete the given path synchronously.
#[napi]
pub fn delete_sync(&self, path: String) -> Result<()> {
self.0.blocking().delete(&path).map_err(format_napi_error)
}
+
+ /// List given path.
+ ///
+ /// This function will create a new handle to list entries.
+ ///
+ /// An error will be returned if given path doesn't end with `/`.
#[napi]
pub async fn list(&self, path: String) -> Result<Lister> {
Ok(Lister(self.0.list(&path).await.map_err(format_napi_error)?))
}
+ /// List given path synchronously.
+ ///
+ /// This function will create a new handle to list entries.
+ ///
+ /// An error will be returned if given path doesn't end with `/`.
#[napi]
pub fn list_sync(&self, path: String) -> Result<BlockingLister> {
Ok(BlockingLister(
@@ -191,6 +214,7 @@ pub struct Entry(opendal::Entry);
#[napi]
impl Entry {
+ // Return the path of this entry.
#[napi]
pub fn path(&self) -> String {
self.0.path().to_string()
diff --git a/bindings/nodejs/typedoc.json b/bindings/nodejs/typedoc.json
new file mode 100644
index 00000000..65499454
--- /dev/null
+++ b/bindings/nodejs/typedoc.json
@@ -0,0 +1,15 @@
+{
+ "entryPoints": ["index.d.ts"],
+ "out": "docs",
+ "name": "Apache OpenDAL",
+ "tsconfig": "tsconfig.json",
+ "excludePrivate": true,
+ "excludeProtected": true,
+ "excludeExternals": true,
+ "includeVersion": true,
+ "githubPages": false,
+ "navigationLinks": {
+ "Homepage": "https://opendal.apache.org/",
+ "GitHub": "https://github.com/apache/incubator-opendal/tree/main/bindings/nodejs"
+ }
+}
diff --git a/bindings/nodejs/yarn.lock b/bindings/nodejs/yarn.lock
index f08f4ba8..166604a7 100644
--- a/bindings/nodejs/yarn.lock
+++ b/bindings/nodejs/yarn.lock
@@ -304,6 +304,13 @@ __metadata:
languageName: node
linkType: hard
+"ansi-sequence-parser@npm:^1.1.0":
+ version: 1.1.0
+ resolution: "ansi-sequence-parser@npm:1.1.0"
+ checksum: 75f4d3a4c555655a698aec05b5763cbddcd16ccccdbfd178fb0aa471ab74fdf98e031b875ef26e64be6a95cf970c89238744b26de6e34af97f316d5186b1df53
+ languageName: node
+ linkType: hard
+
"ansi-styles@npm:^4.0.0":
version: 4.3.0
resolution: "ansi-styles@npm:4.3.0"
@@ -1295,6 +1302,13 @@ __metadata:
languageName: node
linkType: hard
+"jsonc-parser@npm:^3.2.0":
+ version: 3.2.0
+ resolution: "jsonc-parser@npm:3.2.0"
+ checksum: 946dd9a5f326b745aa326d48a7257e3f4a4b62c5e98ec8e49fa2bdd8d96cef7e6febf1399f5c7016114fd1f68a1c62c6138826d5d90bc650448e3cf0951c53c7
+ languageName: node
+ linkType: hard
+
"load-json-file@npm:^7.0.0":
version: 7.0.1
resolution: "load-json-file@npm:7.0.1"
@@ -1334,6 +1348,13 @@ __metadata:
languageName: node
linkType: hard
+"lunr@npm:^2.3.9":
+ version: 2.3.9
+ resolution: "lunr@npm:2.3.9"
+ checksum: 176719e24fcce7d3cf1baccce9dd5633cd8bdc1f41ebe6a180112e5ee99d80373fe2454f5d4624d437e5a8319698ca6837b9950566e15d2cae5f2a543a3db4b8
+ languageName: node
+ linkType: hard
+
"make-fetch-happen@npm:^10.0.3":
version: 10.2.1
resolution: "make-fetch-happen@npm:10.2.1"
@@ -1367,6 +1388,15 @@ __metadata:
languageName: node
linkType: hard
+"marked@npm:^4.2.12":
+ version: 4.2.12
+ resolution: "marked@npm:4.2.12"
+ bin:
+ marked: bin/marked.js
+ checksum: bd551cd61028ee639d4ca2ccdfcc5a6ba4227c1b143c4538f3cde27f569dcb57df8e6313560394645b418b84a7336c07ab1e438b89b6324c29d7d8cdd3102d63
+ languageName: node
+ linkType: hard
+
"matcher@npm:^5.0.0":
version: 5.0.0
resolution: "matcher@npm:5.0.0"
@@ -1437,6 +1467,15 @@ __metadata:
languageName: node
linkType: hard
+"minimatch@npm:^7.1.3":
+ version: 7.4.2
+ resolution: "minimatch@npm:7.4.2"
+ dependencies:
+ brace-expansion: ^2.0.1
+ checksum: 9e341b04e69d5ab03e4206dcb61c8a158e3b8709628bf5e1a4eaa9f3b72c0ba925e24ad959b1f6ce6835caa5a927131d5087fae6836b69e7d99d7d5e63ef0bd8
+ languageName: node
+ linkType: hard
+
"minipass-collect@npm:^1.0.2":
version: 1.0.2
resolution: "minipass-collect@npm:1.0.2"
@@ -1619,6 +1658,7 @@ __metadata:
"@swc/core": ^1.3.38
"@types/node": ^18.14.5
ava: ^5.2.0
+ typedoc: ^0.23.26
typescript: ^4.9.5
languageName: unknown
linkType: soft
@@ -1894,6 +1934,18 @@ __metadata:
languageName: node
linkType: hard
+"shiki@npm:^0.14.1":
+ version: 0.14.1
+ resolution: "shiki@npm:0.14.1"
+ dependencies:
+ ansi-sequence-parser: ^1.1.0
+ jsonc-parser: ^3.2.0
+ vscode-oniguruma: ^1.7.0
+ vscode-textmate: ^8.0.0
+ checksum: b19ea337cc84da69d99ca39d109f82946e0c56c11cc4c67b3b91cc14a9479203365fd0c9e0dd87e908f493ab409dc6f1849175384b6ca593ce7da884ae1edca2
+ languageName: node
+ linkType: hard
+
"signal-exit@npm:^3.0.7":
version: 3.0.7
resolution: "signal-exit@npm:3.0.7"
@@ -2107,6 +2159,22 @@ __metadata:
languageName: node
linkType: hard
+"typedoc@npm:^0.23.26":
+ version: 0.23.26
+ resolution: "typedoc@npm:0.23.26"
+ dependencies:
+ lunr: ^2.3.9
+ marked: ^4.2.12
+ minimatch: ^7.1.3
+ shiki: ^0.14.1
+ peerDependencies:
+ typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x
+ bin:
+ typedoc: bin/typedoc
+ checksum: 09dbd221b5bd27a7f6c593a6aa7e4efc3c46f20761e109a76bf0ed7239011cca1261357094710c01472582060d75a7558aab5bf5b78db3aff7c52188d146ee65
+ languageName: node
+ linkType: hard
+
"typescript@npm:^4.9.5":
version: 4.9.5
resolution: "typescript@npm:4.9.5"
@@ -2152,6 +2220,20 @@ __metadata:
languageName: node
linkType: hard
+"vscode-oniguruma@npm:^1.7.0":
+ version: 1.7.0
+ resolution: "vscode-oniguruma@npm:1.7.0"
+ checksum: 53519d91d90593e6fb080260892e87d447e9b200c4964d766772b5053f5699066539d92100f77f1302c91e8fc5d9c772fbe40fe4c90f3d411a96d5a9b1e63f42
+ languageName: node
+ linkType: hard
+
+"vscode-textmate@npm:^8.0.0":
+ version: 8.0.0
+ resolution: "vscode-textmate@npm:8.0.0"
+ checksum: 127780dfea89559d70b8326df6ec344cfd701312dd7f3f591a718693812b7852c30b6715e3cfc8b3200a4e2515b4c96f0843c0eacc0a3020969b5de262c2a4bb
+ languageName: node
+ linkType: hard
+
"well-known-symbols@npm:^2.0.0":
version: 2.0.0
resolution: "well-known-symbols@npm:2.0.0"
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index db0072e6..25098661 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -92,8 +92,12 @@ const config = {
label: 'Documentation',
items: [
{
- label: 'Rust',
- to: '/docs/rust/opendal/'
+ type: 'html',
+ value: '<a class="dropdown__link" href="/docs/rust/opendal">Rust</a>'
+ },
+ {
+ type: 'html',
+ value: '<a class="dropdown__link" href="/docs/nodejs/">Node.js</a>'
},
]
},
diff --git a/website/src/pages/index.js b/website/src/pages/index.js
index c9ab7a1f..546ceb8f 100644
--- a/website/src/pages/index.js
+++ b/website/src/pages/index.js
@@ -38,7 +38,7 @@ function HomepageHeader() {
<div className={styles.buttons}>
<a
className="button button--secondary button--lg"
- href="/docs/rust/opendal/index.html">
+ href="/docs/rust/opendal">
Get Start
</a>
</div>