From 9ba855c58c265afba5413848c0dfd91687c80a86 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 00:57:08 +0800 Subject: [PATCH 1/9] doc(binding/lua): add ldoc generate comment lua file Signed-off-by: owl --- bindings/lua/src/metadata_doc.lua | 19 ++++++++++++ bindings/lua/src/operator_doc.lua | 48 +++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 bindings/lua/src/metadata_doc.lua create mode 100644 bindings/lua/src/operator_doc.lua diff --git a/bindings/lua/src/metadata_doc.lua b/bindings/lua/src/metadata_doc.lua new file mode 100644 index 000000000000..61ec3086c5ce --- /dev/null +++ b/bindings/lua/src/metadata_doc.lua @@ -0,0 +1,19 @@ +--- OpenDAL metadata It must be returned operator::stat() +-- @classmod opendal.metadata +-- @pragma nostrip + +local _M = {} + +--- Return whether the path represents a file +-- @return bool if it is file, otherwise false +-- @function is_file + +--- Return whether the path represents a directory +-- @return bool if it is directory, otherwise false +-- @function is_dir + +--- Return the content_length of the metadata +-- @return bool if it is directory, otherwise false +-- @function content_length + +return _M \ No newline at end of file diff --git a/bindings/lua/src/operator_doc.lua b/bindings/lua/src/operator_doc.lua new file mode 100644 index 000000000000..719d3e83b573 --- /dev/null +++ b/bindings/lua/src/operator_doc.lua @@ -0,0 +1,48 @@ +--- OpenDAL operator. +-- @classmod opendal.operator +-- @pragma nostrip + +local _M = {} + +--- Construct an operator based on scheme and option. Uses an table of key-value pairs to initialize +--- the operator based on provided scheme and options. For each scheme, i.e. Backend, +--- different options could be set, you may reference the https://opendal.apache.org/docs/category/services/ +--- for each service, especially for the **Configuration Part**. +-- @param string scheme the service scheme you want to specify, e.g. "fs", "s3", "supabase" +-- @param table options the table to the options for this operators +-- @return table, error opendal operator table which contain opendal operator instance, error nil if sucess, others otherwise +-- @function new + + +--- Blockingly write raw bytes to path. +--- Write the bytes into the path blockingly, returns nil if succeeds, others otherwise +-- @param string path the designated path you want to write your bytes in +-- @param string bytes the bytes to be written +-- @return error nil if success, otherwise error message +-- @function write + +--- Blockingly read raw bytes from path. +--- Read the data out from `path` blockingly by operator, returns the string if succeeds, others otherwise +-- @param string path the designated path you want to write your bytes in +-- @return string, error readed data, error nil if success, otherwise error message +-- @function read + +--- Blockingly delete the object in path. +--- Delete the object in path blockingly, returns error nil +--- if succeeds, others otherwise +-- @param string path the designated path you want to write your delete +-- @return error error nil if success, otherwise error message +-- @function delete + +--- Check whether the path exists. +-- @param string path the designated path you want to write your delete +-- @return bool, error true or false depend on operator instance and path, error nil if success, otherwise error message +-- @function is_exist + +--- Stat the path, return its metadata. +-- @param string ,path the designated path you want to write your delete +-- @return table , error opendal.metadata instance table, error nil if success, otherwise error message +-- @function stat + + +return _M \ No newline at end of file From 426547ac804def69328cf8338c9473574bfa273a Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 01:08:40 +0800 Subject: [PATCH 2/9] doc(binding/lua): add ldoc github action Signed-off-by: owl --- .github/workflows/docs.yml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a3547cd98b25..f9ad6e8360af 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -163,6 +163,21 @@ jobs: with: name: C-docs path: ./bindings/c/docs/doxygen/html + build-lua-doc: + runs-on: ubuntu-latest + + steps: + - name: Generate docs with LDoc + uses: lunarmodules/ldoc@v0 + with: + args: bindings/lua/src -d bindings/lua/doc + + - name: Upload docs + uses: actions/upload-artifact@v3 + with: + name: lua-docs + path: ./bindings/c/doc/ + build-website: runs-on: ubuntu-latest @@ -216,6 +231,12 @@ jobs: name: C-docs path: ./website/static/docs/c + - name: Download lua docs + uses: actions/download-artifact@v3 + with: + name: lua-docs + path: ./website/static/docs/lua + - name: Install Dependencies working-directory: website run: yarn install --immutable From 7446dd83b940033bab66c9df62a394964c6a81af Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 01:11:12 +0800 Subject: [PATCH 3/9] doc(binding/lua): fix code Signed-off-by: owl --- bindings/lua/src/metadata_doc.lua | 24 +++++++++++++++++++++++- bindings/lua/src/operator_doc.lua | 23 ++++++++++++++++++++++- 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/bindings/lua/src/metadata_doc.lua b/bindings/lua/src/metadata_doc.lua index 61ec3086c5ce..95d63baacd03 100644 --- a/bindings/lua/src/metadata_doc.lua +++ b/bindings/lua/src/metadata_doc.lua @@ -1,3 +1,25 @@ +--[[ + + 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. + +]] + + --- OpenDAL metadata It must be returned operator::stat() -- @classmod opendal.metadata -- @pragma nostrip @@ -16,4 +38,4 @@ local _M = {} -- @return bool if it is directory, otherwise false -- @function content_length -return _M \ No newline at end of file +return _M diff --git a/bindings/lua/src/operator_doc.lua b/bindings/lua/src/operator_doc.lua index 719d3e83b573..f83196c39991 100644 --- a/bindings/lua/src/operator_doc.lua +++ b/bindings/lua/src/operator_doc.lua @@ -1,3 +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. + +]] + --- OpenDAL operator. -- @classmod opendal.operator -- @pragma nostrip @@ -45,4 +66,4 @@ local _M = {} -- @function stat -return _M \ No newline at end of file +return _M From 07461c044d14232b3721f5a537528df8f32d2736 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 01:13:43 +0800 Subject: [PATCH 4/9] doc(binding/lua): fix code Signed-off-by: owl --- bindings/lua/src/operator_doc.lua | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/bindings/lua/src/operator_doc.lua b/bindings/lua/src/operator_doc.lua index f83196c39991..f863cc4f4926 100644 --- a/bindings/lua/src/operator_doc.lua +++ b/bindings/lua/src/operator_doc.lua @@ -31,26 +31,26 @@ local _M = {} --- for each service, especially for the **Configuration Part**. -- @param string scheme the service scheme you want to specify, e.g. "fs", "s3", "supabase" -- @param table options the table to the options for this operators --- @return table, error opendal operator table which contain opendal operator instance, error nil if sucess, others otherwise +-- @return table, error opendal operator table which contain opendal operator instance, error nil if success, others otherwise -- @function new --- Blockingly write raw bytes to path. ---- Write the bytes into the path blockingly, returns nil if succeeds, others otherwise +--- Write the bytes into the path blockingly, returns nil if success, others otherwise -- @param string path the designated path you want to write your bytes in -- @param string bytes the bytes to be written -- @return error nil if success, otherwise error message -- @function write --- Blockingly read raw bytes from path. ---- Read the data out from `path` blockingly by operator, returns the string if succeeds, others otherwise +--- Read the data out from `path` blockingly by operator, returns the string if success, others otherwise -- @param string path the designated path you want to write your bytes in --- @return string, error readed data, error nil if success, otherwise error message +-- @return string, error read data, error nil if success, otherwise error message -- @function read --- Blockingly delete the object in path. --- Delete the object in path blockingly, returns error nil ---- if succeeds, others otherwise +--- if success, others otherwise -- @param string path the designated path you want to write your delete -- @return error error nil if success, otherwise error message -- @function delete From 5c225aacbf4af493803457022c7690123b633226 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 09:40:01 +0800 Subject: [PATCH 5/9] doc(binding/lua): fix code Signed-off-by: owl --- .github/workflows/docs.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f9ad6e8360af..0513b4e030e0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -167,10 +167,12 @@ jobs: runs-on: ubuntu-latest steps: - - name: Generate docs with LDoc - uses: lunarmodules/ldoc@v0 - with: - args: bindings/lua/src -d bindings/lua/doc + - name: Setup doxygen + run: sudo apt-get install lua-ldoc + + - name: Build Docs + working-directory: bindings/lua + run: ldoc src - name: Upload docs uses: actions/upload-artifact@v3 From 27c4ce1106fcf7f5bbe4e16c95f1c0cdc9d44c47 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 09:41:12 +0800 Subject: [PATCH 6/9] doc(binding/lua): fix code Signed-off-by: owl --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0513b4e030e0..32015e2fc44b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -178,7 +178,7 @@ jobs: uses: actions/upload-artifact@v3 with: name: lua-docs - path: ./bindings/c/doc/ + path: ./bindings/lua/doc/ build-website: From c221623404a4d27c371615fc323c5174e9603249 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 09:45:13 +0800 Subject: [PATCH 7/9] doc(binding/lua): fix code Signed-off-by: owl --- .github/workflows/docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 32015e2fc44b..4dc1cebe18ca 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -167,12 +167,12 @@ jobs: runs-on: ubuntu-latest steps: - - name: Setup doxygen + - name: Setup lua-ldoc run: sudo apt-get install lua-ldoc - name: Build Docs - working-directory: bindings/lua - run: ldoc src + working-directory: "bindings/lua" + run: ldoc ./src - name: Upload docs uses: actions/upload-artifact@v3 From e80c231e6c2fd4f06d99516ebd26b500ccd0a4f9 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 10:18:46 +0800 Subject: [PATCH 8/9] doc(binding/lua): fix code Signed-off-by: owl --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4dc1cebe18ca..3f87a3a053dd 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -167,6 +167,8 @@ jobs: runs-on: ubuntu-latest steps: + - uses: actions/checkout@v3 + - name: Setup lua-ldoc run: sudo apt-get install lua-ldoc From 7bc429db6168f4f59fce8c1880705f28bf6503c7 Mon Sep 17 00:00:00 2001 From: owl Date: Tue, 27 Jun 2023 11:54:36 +0800 Subject: [PATCH 9/9] doc(binding/lua): fix code Signed-off-by: owl --- website/docusaurus.config.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index fb0c70891ca9..65a8bd67d61f 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -129,6 +129,10 @@ const config = { label: 'C Binding', to: 'pathname:///docs/c/' }, + { + label: 'Lua Binding', + to: 'pathname:///docs/lua/' + }, ] }, {