mosn · wenxuwan · Jun 13, 2022 · Jun 9, 2022 · Jun 10, 2022 · Jun 10, 2022
diff --git a/Makefile b/Makefile
@@ -75,6 +75,7 @@ include make/golang.mk
 include make/image.mk
 include make/wasm.mk
 include make/ci.mk
+include make/proto.mk
 
 # ==============================================================================
 # Targets:
@@ -246,6 +247,27 @@ format: go.format
 clean:
 	@$(MAKE) go.clean
 
+# ==============================================================================
+## proto.doc: Generate documentation according to the proto files.
+# ==============================================================================
+.PHONY: proto.doc
+proto.doc:
+	@$(MAKE) proto.gen.doc
+
+# ==============================================================================
+## proto.init: Install protoc-gen-go and protoc-gen-go-grpc
+# ==============================================================================
+.PHONY: proto.init
+proto.init:
+	@$(MAKE) proto.gen.init
+
+# ==============================================================================
+## proto.code: Generate pb.go code according to the proto files.
+# ==============================================================================
+.PHONY: proto.code
+proto.code:
+	@$(MAKE) proto.gen.code
+
 # ==============================================================================
 ## all: Run format codes, check codes, build Layotto codes for host platform with one command
 # ==============================================================================

diff --git a/docker/proto/Dockerfile b/docker/proto/Dockerfile
@@ -0,0 +1,38 @@
+# Copyright 2021 Layotto Authors
+# Licensed 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.
+
+FROM golang:1.16
+
+# install unzip
+RUN apt-get update
+RUN apt-get install -y unzip
+
+WORKDIR /api
+
+# install protoc
+RUN PB_REL="https://github.com/protocolbuffers/protobuf/releases" && \
+    curl -LO $PB_REL/download/v3.17.3/protoc-3.17.3-linux-x86_64.zip
+
+RUN unzip protoc-3.17.3-linux-x86_64.zip -d /api/protoc
+
+ENV PATH="$PATH:/api/protoc/bin"
+RUN protoc --version
+
+# install protoc-gen-go and protoc-gen-go-grpc
+RUN go install google.golang.org/protobuf/cmd/[email protected]
+RUN go install google.golang.org/grpc/cmd/[email protected]
+
+WORKDIR /api/proto
+
+# generate code
+CMD protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=require_unimplemented_servers=false,paths=source_relative *.proto
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -80,10 +80,10 @@
   - [Document Contribution Guide](en/development/contributing-doc.md)
   - [Automate testing of Quickstart documentation with tools](en/development/test-quickstart.md)
   - [Component Development Guide](en/development/developing-component.md)
-  - You wanna modify proto files or API definition?
+  - Want to modify proto files or API definition?
     - [Development specification when adding API](en/development/developing-api.md)
     - [Comment specification of proto file](en/api_reference/comment_spec_of_proto.md)
-    - [How to generate API document based on the proto files](en/api_reference/how_to_generate_api_doc.md)
+    - [How to generate pb code and API reference](en/api_reference/how_to_generate_api_doc.md)
   - [Layotto Github Workflows Guide](en/development/github-workflows.md)
   - [Layotto Commands Guide](en/development/commands.md)
   - [Layotto contributor guide](en/development/CONTRIBUTING.md)

diff --git a/docs/en/api_reference/how_to_generate_api_doc.md b/docs/en/api_reference/how_to_generate_api_doc.md
@@ -1,7 +1,38 @@
-# How to generate api documents
+# How to generate `.pb.go` code and API reference
+Note: the commands below should be executed under layotto directory
 
+## How to compile the proto files into `.pb.go` code
+<!-- tabs:start -->
+### **Make cmmand(recommended)**
+```bash
+make proto.code
+```
+This command uses docker to run protoc and generate `.pb.go` code files.
+
+### **Install protoc**
+1. Install protoc version: [v3.17.3](https://github.com/protocolbuffers/protobuf/releases/tag/v3.17.3)
+
+2. Install protoc-gen-go v1.28 and protoc-gen-go-grpc v1.2
+
+3. Generate gRPC `.pb.go` code
+
+```bash
+cd spec/proto/runtime/v1
+protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=require_unimplemented_servers=false,paths=source_relative *.proto
+```
+<!-- tabs:end -->
+## How to generate API reference doc according to the proto files
 We can use [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) and docker to generate api documents,the command is as follows:  
-(Run in layotto directory)
+
+<!-- tabs:start -->
+### **Make command(recommended)**
+```bash
+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:
 
 ```
 docker run --rm \
@@ -17,4 +48,6 @@ 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
-```
+```
+
+<!-- tabs:end -->
diff --git a/docs/zh/_sidebar.md b/docs/zh/_sidebar.md
@@ -99,7 +99,7 @@
     - 想要修改proto文件或API定义？
         - [新增API时的开发规范](zh/development/developing-api.md)
         - [proto文件注释规范](zh/api_reference/comment_spec_of_proto.md)
-        - [如何基于proto文件生成接口文档](zh/api_reference/how_to_generate_api_doc.md)  
+        - [如何基于proto文件生成代码、接口文档](zh/api_reference/how_to_generate_api_doc.md)  
     - [Layotto 四大 Github Workflows 说明](zh/development/github-workflows.md)
     - [Layotto 命令行工具指南](zh/development/commands.md)
     - [发布手册](zh/development/release-guide.md)

diff --git a/docs/zh/api_reference/how_to_generate_api_doc.md b/docs/zh/api_reference/how_to_generate_api_doc.md
@@ -1,8 +1,44 @@
-# 如何基于proto文件生成接口文档
+# 如何基于proto文件生成代码、接口文档
 
+## 如何把 proto 文件编译成`.pb.go`代码
+<!-- tabs:start -->
+### **Make 命令生成(推荐)**
+本地启动 docker 后，在项目根目录下运行：
 
-我们可以用[protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) 和docker来生成接口文档，相关命令如下：  
-(需要在layotto项目下运行命令)
+```bash
+make proto.code
+```
+该命令会用 docker 启动 protoc，生成`.pb.go`代码。
+
+这种方式更方便，开发者不需要修改本地 protoc 版本，省去了很多烦恼。
+
+### **手动安装工具**
+1. Install protoc version: [v3.17.3](https://github.com/protocolbuffers/protobuf/releases/tag/v3.17.3)
+
+2. Install protoc-gen-go v1.28 and protoc-gen-go-grpc v1.2
+
+3. Generate gRPC `.pb.go` code
+
+```bash
+cd spec/proto/runtime/v1
+protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=require_unimplemented_servers=false,paths=source_relative *.proto
+```
+<!-- tabs:end -->
+## 如何基于proto文件生成接口文档
+
+我们可以用[protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) 和docker来生成接口文档，相关命令如下：
+
+<!-- tabs:start -->
+### **Make 命令生成(推荐)**
+本地启动 docker 后，在项目根目录下运行：
+
+```bash
+make proto.doc
+```
+该命令会用 docker 启动 protoc-gen-doc，生成文档
+
+### **用 docker 启动 protoc-gen-doc**
+`make proto.doc` 等价于执行以下命令:
 
 ```
 docker run --rm \
@@ -18,4 +54,5 @@ 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
-```
+```
+<!-- tabs:end -->
diff --git a/make/proto.mk b/make/proto.mk
@@ -0,0 +1,35 @@
+# Copyright 2021 Layotto Authors
+# Licensed 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.
+
+.PHONY: proto.gen.doc
+proto.gen.doc:
+	$(DOCKER) run --rm \
+    -v  $(ROOT_DIR)/docs/en/api_reference:/out \
+    -v  $(ROOT_DIR)/spec/proto/runtime/v1:/protos \
+    pseudomuto/protoc-gen-doc  --doc_opt=/protos/template.tmpl,runtime_v1.md runtime.proto
+	$(DOCKER) run --rm \
+    -v  $(ROOT_DIR)/docs/en/api_reference:/out \
+    -v  $(ROOT_DIR)/spec/proto/runtime/v1:/protos \
+    pseudomuto/protoc-gen-doc  --doc_opt=/protos/template.tmpl,appcallback_v1.md appcallback.proto
+
+.PHONY: proto.gen.init
+proto.gen.init:
+	 go install google.golang.org/protobuf/cmd/[email protected]
+	 go install google.golang.org/grpc/cmd/[email protected]
+
+.PHONY: proto.gen.code
+proto.gen.code:
+	$(DOCKER) build -t layotto/protoc $(ROOT_DIR)/docker/proto && \
+	$(DOCKER) run --rm \
+		-v  $(ROOT_DIR)/spec/proto/runtime/v1:/api/proto \
+		layotto/protoc
diff --git a/spec/proto/runtime/v1/README.md b/spec/proto/runtime/v1/README.md
@@ -1,12 +1,3 @@
 
-## How to compile these proto files into golang code
-```shell
-cd ${your PROJECT path}/spec/proto/runtime/v1
-protoc -I.  --go_out=plugins=grpc,paths=source_relative:. *.proto
-```
-
-my protoc version: 
-```shell
-$ protoc --version
-libprotoc 3.11.2
-```
+## How to compile these proto files into golang code and documentation
+Please visit https://mosn.io/layotto/#/en/api_reference/how_to_generate_api_doc