feat: doc generator

docs/_sidebar.md

@@ -13,7 +13,9 @@
   - Service Invocation
     - [Hello World](en/start/rpc/helloworld.md)
     - [Dubbo JSON RPC](en/start/rpc/dubbo_json_rpc.md)    
+  - [Use OSS API](en/start/oss/start.md)
   - [API plugin: register your own API](en/start/api_plugin/helloworld.md)
+  <!--quickstart_generator-->  
   - As the data plane of istio
     - [Integrate with istio 1.10.6](en/start/istio/)
     - [Integrate with istio 1.5.x](en/start/istio/start.md)

docs/api/v1/s3.html

@@ -515,7 +515,7 @@ <h2 id="oss.proto">oss.proto</h2><a href="#title">Top</a>
 
 
         <h3 id="spec.proto.extension.v1.s3.ObjectStorageService">[gRPC Service] ObjectStorageService</h3>
-        <p>ObjectStorageService</p>
+        <p>ObjectStorageService is an abstraction for blob storage or so called "object storage", such as alibaba cloud OSS, such as AWS S3.</p><p>You invoke ObjectStorageService API to do some CRUD operations on your binary file, e.g. query my file, delete my file, etc.</p>
         <table class="enum-table">
           <thead>
             <tr><td>Method Name</td><td>Request Type</td><td>Response Type</td><td>Description</td></tr>

docs/en/api_reference/how_to_generate_api_doc.md

@@ -1,4 +1,4 @@
-# How to generate `.pb.go` code and API reference
+# How to generate `.pb.go` code and corresponding documentation
 Note: the commands below should be executed under layotto directory
 
 ```shell
@@ -8,7 +8,10 @@ make proto
 Then you get:
 - `.pb.go` code
 - API reference docs
-- updated sidebar in the doc site
+- updated API reference list
+- quickstart document (both chinese and english)
+- updated sidebar (The tool will add the generated quickstart doc into the sidebar of https://mosn.io/layotto )
+- updated CI (The tool will add the generated quickstart doc into the CI script `etc/script/test-quickstart.sh`)
 
 That's all :)
 
@@ -48,22 +51,8 @@ make proto.doc
 This command uses docker to run protoc-gen-doc and generate docs.
 
 ### **Use docker to run protoc-gen-doc**
-`make proto.doc` essentially run commands below:
+`make proto.doc` invokes the script `etc/script/generate-doc.sh`, which uses docker to run protoc-gen-doc.
 
-```
-docker run --rm \
--v  $(pwd)/docs/en/api_reference:/out \
--v  $(pwd)/spec/proto/runtime/v1:/protos \
-pseudomuto/protoc-gen-doc  --doc_opt=/protos/template.tmpl,runtime_v1.md runtime.proto
-```
-
-and 
-
-```shell
-docker run --rm \
--v  $(pwd)/docs/en/api_reference:/out \
--v  $(pwd)/spec/proto/runtime/v1:/protos \
-pseudomuto/protoc-gen-doc  --doc_opt=/protos/template.tmpl,appcallback_v1.md appcallback.proto
-```
+You can check `etc/script/generate-doc.sh` for more details.
 
 <!-- tabs:end -->

docs/en/building_blocks/rpc/reference.md

@@ -4,7 +4,7 @@ Layotto's RPC API is based on [Mosn](https://mosn.io/en/)'s grpc handler, which
 
 The interface of the RPC API are consistent with [Dapr](https://docs.dapr.io/developing-applications/building-blocks/service-invocation/service-invocation-overview/), you could see its details in [invoke.go](https://github.com/mosn/layotto/blob/3802c4591181fdbcfb7dd07cbbdbadeaaada650a/sdk/go-sdk/client/invoke.go).
 
-Using Layotto RPC invocation, your application can reliably and securely communicate with other applications using the standard  HTTP or [X-Protocol](https://www.servicemesher.com/blog/x-protocol-common-address-solution/) protocols.
+Using Layotto RPC invocation, your application can reliably and securely communicate with other applications using the standard  HTTP or [X-Protocol](https://cloudnative.to/blog/x-protocol-common-address-solution/) protocols.
 
 ![sidecar](https://mosn.io/en/docs/concept/sidecar-pattern/sidecar-pattern.jpg)
 

docs/en/start/oss/start.md

@@ -0,0 +1,153 @@
+
+# ObjectStorageService API demo
+
+This example shows how to invoke Layotto ObjectStorageService API.
+
+ObjectStorageService is an abstraction for blob storage or so called "object storage", such as alibaba cloud OSS, such as AWS S3.
+You invoke ObjectStorageService API to do some CRUD operations on your binary file, e.g. query my file, delete my file, etc.
+
+## step 0. modify the configuration
+Please modify the OSS configuration in the `configs/config_oss.json`
+
+```json
+"grpc_config": {
+  "oss": {
+    "oss_demo": {
+      "type": "aws.oss",
+      "metadata": {
+        "basic_config":{
+          "region": "your-oss-resource-region",
+          "endpoint": "your-oss-resource-endpoint",
+          "accessKeyID": "your-oss-resource-accessKeyID",
+          "accessKeySecret": "your-oss-resource-accessKeySecret"
+        }
+      }
+    }
+  }
+}
+```
+
+## step 1. Deploy Layotto
+<!-- tabs:start -->
+### **With Docker**
+You can start Layotto with docker
+
+```bash
+docker run -v "$(pwd)/configs/config_oss.json:/runtime/configs/config.json" -d  -p 34904:34904 --name layotto layotto/layotto start
+```
+
+### **Compile locally (not for Windows)**
+You can compile and run Layotto locally.
+
+> [!TIP|label: Not for Windows users]
+> Layotto fails to compile under Windows. Windows users are recommended to deploy using docker-compose
+
+After downloading the project code to the local, switch the code directory and compile:
+
+```shell
+cd ${project_path}/cmd/layotto
+```
+
+```shell @if.not.exist layotto
+go build
+```
+
+Once finished, the layotto binary will be generated in the directory.
+
+Run it:
+
+```shell @background
+./layotto start -c ../../configs/config_oss.json
+```
+
+<!-- tabs:end -->
+
+## step 2. Run the client program to invoke Layotto ObjectStorageService API
+<!-- tabs:start -->
+### **Go**
+Build and run the golang [demo](https://github.com/mosn/layotto/blob/main/demo/oss/client.go) :
+
+```shell
+cd ${project_path}/demo/oss/
+go build client.go
+
+# upload test3.txt with content "hello" to the bucket named `antsys-wenxuwan`
+./client put antsys-wenxuwan test3.txt "hello"
+
+# get test3.txt in the bucket antsys-wenxuwan
+./client get antsys-wenxuwan test3.txt
+
+# delete test3.txt
+./client del antsys-wenxuwan test3.txt
+
+# list the files in the bucket antsys-wenxuwan
+./client list antsys-wenxuwan
+
+```
+
+### **Java**
+<!-- 
+
+Download java sdk and examples:
+
+```shell @if.not.exist java-sdk
+git clone https://github.com/layotto/java-sdk
+```
+
+```shell
+cd java-sdk
+```
+
+Build the demo:
+
+```shell @if.not.exist examples-oss/target/examples-oss-1.1.0-jar-with-dependencies.jar
+# build example jar
+mvn -f examples-oss/pom.xml clean package
+```
+
+Run it:
+
+```shell
+java -jar examples-oss/target/examples-oss-1.1.0-jar-with-dependencies.jar
+```
+
+If the following information is printed, the demo is successful:
+
+```bash
+TODO
+```
+
+-->
+
+<!-- tabs:end -->
+
+## step 3. Stop containers and release resources
+<!-- tabs:start -->
+### **Destroy the Docker container**
+If you started Layotto with docker, you can destroy the container as follows:
+
+```bash
+docker rm -f layotto
+```
+
+<!-- tabs:end -->
+
+## Next step
+### What does this client program do?
+The demo client program uses the SDK provided by Layotto to invoke the Layotto ObjectStorageService API.
+
+The golang sdk is located in the `sdk` directory, and the java sdk is in https://github.com/layotto/java-sdk
+
+In addition to using sdk, you can also interact with Layotto directly through grpc in any language you like.
+
+### Details later, let's continue to experience other APIs
+Explore other Quickstarts through the navigation bar on the left.
+
+### Reference
+
+[API reference](https://mosn.io/layotto/api/v1/s3.html)
+
+[Design doc of ObjectStorageService API ](zh/design/oss/design)
+
+ <!-- end services -->
+

docs/template/quickstart.tmpl

@@ -0,0 +1,123 @@
+{{range .Files}} {{$file_name := .Name}} {{if .HasServices}} {{range .Services}}
+# {{.Name}} API demo
+
+This example shows how to invoke Layotto {{.Name}} API.
+
+{{.Description}}
+
+## step 1. Deploy Layotto
+<!-- tabs:start -->
+### **With Docker**
+You can start Layotto with docker
+
+```bash
+docker run -v "$(pwd)/configs/config_standalone.json:/runtime/configs/config.json" -d  -p 34904:34904 --name layotto layotto/layotto start
+```
+
+### **Compile locally (not for Windows)**
+You can compile and run Layotto locally.
+
+> [!TIP|label: Not for Windows users]
+> Layotto fails to compile under Windows. Windows users are recommended to deploy using docker
+
+After downloading the project code to the local, switch the code directory and compile:
+
+```shell
+cd ${project_path}/cmd/layotto
+```
+
+```shell @if.not.exist layotto
+go build
+```
+
+Once finished, the layotto binary will be generated in the directory.
+
+Run it:
+
+```shell @background
+./layotto start -c ../../configs/config_standalone.json
+```
+
+<!-- tabs:end -->
+
+## step 2. Run the client program to invoke Layotto {{.Name}} API
+<!-- tabs:start -->
+### **Go**
+Build and run the golang demo:
+
+```shell
+ cd ${project_path}/demo/{{$file_name}}/common/
+ go build -o client
+ ./client -s "demo"
+```
+
+If the following information is printed, the demo is successful:
+
+```bash
+TODO
+```
+
+### **Java**
+
+Download java sdk and examples:
+
+```shell @if.not.exist java-sdk
+git clone https://github.com/layotto/java-sdk
+```
+
+```shell
+cd java-sdk
+```
+
+Build the demo:
+
+```shell @if.not.exist examples-{{$file_name}}/target/examples-{{$file_name}}-1.1.0-jar-with-dependencies.jar
+# build example jar
+mvn -f examples-{{$file_name}}/pom.xml clean package
+```
+
+Run it:
+
+```shell
+java -jar examples-{{$file_name}}/target/examples-{{$file_name}}-1.1.0-jar-with-dependencies.jar
+```
+
+If the following information is printed, the demo is successful:
+
+```bash
+TODO
+```
+
+<!-- tabs:end -->
+
+## step 3. Stop containers and release resources
+<!-- tabs:start -->
+### **Destroy the Docker container**
+If you started Layotto with docker, you can destroy the container as follows:
+
+```bash
+docker rm -f layotto
+```
+
+<!-- tabs:end -->
+
+## Next step
+### What does this client program do?
+The demo client program uses the SDK provided by Layotto to invoke the Layotto {{.Name}} API.
+
+The golang sdk is located in the `sdk` directory, and the java sdk is in https://github.com/layotto/java-sdk
+
+In addition to using sdk, you can also interact with Layotto directly through grpc in any language you like.
+
+### Details later, let's continue to experience other APIs
+Explore other Quickstarts through the navigation bar on the left.
+
+### Reference
+
+<!--api_reference_url-->
+
+<!--design_doc_url-->
+
+{{end}} <!-- end services -->
+{{end}}
+{{end}}