Skip to content

Commit f3e0110

Browse files
seefloodseeflood
authored
ci: compile proto files into code and doc (#637)
* make proto.doc Signed-off-by: seeflood <[email protected]> * make proto.code Signed-off-by: seeflood <[email protected]> * improve doc Signed-off-by: seeflood <[email protected]> * format Signed-off-by: seeflood <[email protected]> * require_unimplemented_servers=false Signed-off-by: seeflood <[email protected]>
1 parent d4f51fd commit f3e0110

File tree

12 files changed

+1403
-1205
lines changed

12 files changed

+1403
-1205
lines changed

‎Makefile

+22
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ include make/golang.mk
7575
include make/image.mk
7676
include make/wasm.mk
7777
include make/ci.mk
78+
include make/proto.mk
7879

7980
# ==============================================================================
8081
# Targets:
@@ -246,6 +247,27 @@ format: go.format
246247
clean:
247248
@$(MAKE) go.clean
248249

250+
# ==============================================================================
251+
## proto.doc: Generate documentation according to the proto files.
252+
# ==============================================================================
253+
.PHONY: proto.doc
254+
proto.doc:
255+
@$(MAKE) proto.gen.doc
256+
257+
# ==============================================================================
258+
## proto.init: Install protoc-gen-go and protoc-gen-go-grpc
259+
# ==============================================================================
260+
.PHONY: proto.init
261+
proto.init:
262+
@$(MAKE) proto.gen.init
263+
264+
# ==============================================================================
265+
## proto.code: Generate pb.go code according to the proto files.
266+
# ==============================================================================
267+
.PHONY: proto.code
268+
proto.code:
269+
@$(MAKE) proto.gen.code
270+
249271
# ==============================================================================
250272
## all: Run format codes, check codes, build Layotto codes for host platform with one command
251273
# ==============================================================================

‎docker/proto/Dockerfile

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Copyright 2021 Layotto Authors
2+
# Licensed under the Apache License, Version 2.0 (the "License");
3+
# you may not use this file except in compliance with the License.
4+
# You may obtain a copy of the License at
5+
6+
# http://www.apache.org/licenses/LICENSE-2.0
7+
8+
# Unless required by applicable law or agreed to in writing, software
9+
# distributed under the License is distributed on an "AS IS" BASIS,
10+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
# See the License for the specific language governing permissions and
12+
# limitations under the License.
13+
14+
FROM golang:1.16
15+
16+
# install unzip
17+
RUN apt-get update
18+
RUN apt-get install -y unzip
19+
20+
WORKDIR /api
21+
22+
# install protoc
23+
RUN PB_REL="https://github.com/protocolbuffers/protobuf/releases" && \
24+
curl -LO $PB_REL/download/v3.17.3/protoc-3.17.3-linux-x86_64.zip
25+
26+
RUN unzip protoc-3.17.3-linux-x86_64.zip -d /api/protoc
27+
28+
ENV PATH="$PATH:/api/protoc/bin"
29+
RUN protoc --version
30+
31+
# install protoc-gen-go and protoc-gen-go-grpc
32+
RUN go install google.golang.org/protobuf/cmd/[email protected]
33+
RUN go install google.golang.org/grpc/cmd/[email protected]
34+
35+
WORKDIR /api/proto
36+
37+
# generate code
38+
CMD protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=require_unimplemented_servers=false,paths=source_relative *.proto

‎docs/_sidebar.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -80,10 +80,10 @@
8080
- [Document Contribution Guide](en/development/contributing-doc.md)
8181
- [Automate testing of Quickstart documentation with tools](en/development/test-quickstart.md)
8282
- [Component Development Guide](en/development/developing-component.md)
83-
- You wanna modify proto files or API definition?
83+
- Want to modify proto files or API definition?
8484
- [Development specification when adding API](en/development/developing-api.md)
8585
- [Comment specification of proto file](en/api_reference/comment_spec_of_proto.md)
86-
- [How to generate API document based on the proto files](en/api_reference/how_to_generate_api_doc.md)
86+
- [How to generate pb code and API reference](en/api_reference/how_to_generate_api_doc.md)
8787
- [Layotto Github Workflows Guide](en/development/github-workflows.md)
8888
- [Layotto Commands Guide](en/development/commands.md)
8989
- [Layotto contributor guide](en/development/CONTRIBUTING.md)

‎docs/en/api_reference/how_to_generate_api_doc.md

+36-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,38 @@
1-
# How to generate api documents
1+
# How to generate `.pb.go` code and API reference
2+
Note: the commands below should be executed under layotto directory
23

4+
## How to compile the proto files into `.pb.go` code
5+
<!-- tabs:start -->
6+
### **Make cmmand(recommended)**
7+
```bash
8+
make proto.code
9+
```
10+
This command uses docker to run protoc and generate `.pb.go` code files.
11+
12+
### **Install protoc**
13+
1. Install protoc version: [v3.17.3](https://github.com/protocolbuffers/protobuf/releases/tag/v3.17.3)
14+
15+
2. Install protoc-gen-go v1.28 and protoc-gen-go-grpc v1.2
16+
17+
3. Generate gRPC `.pb.go` code
18+
19+
```bash
20+
cd spec/proto/runtime/v1
21+
protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=require_unimplemented_servers=false,paths=source_relative *.proto
22+
```
23+
<!-- tabs:end -->
24+
## How to generate API reference doc according to the proto files
325
We can use [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) and docker to generate api documents,the command is as follows:
4-
(Run in layotto directory)
26+
27+
<!-- tabs:start -->
28+
### **Make command(recommended)**
29+
```bash
30+
make proto.doc
31+
```
32+
This command uses docker to run protoc-gen-doc and generate docs.
33+
34+
### **Use docker to run protoc-gen-doc**
35+
`make proto.doc` essentially run commands below:
536

637
```
738
docker run --rm \
@@ -17,4 +48,6 @@ docker run --rm \
1748
-v $(pwd)/docs/en/api_reference:/out \
1849
-v $(pwd)/spec/proto/runtime/v1:/protos \
1950
pseudomuto/protoc-gen-doc --doc_opt=/protos/template.tmpl,appcallback_v1.md appcallback.proto
20-
```
51+
```
52+
53+
<!-- tabs:end -->

‎docs/zh/_sidebar.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@
9999
- 想要修改proto文件或API定义？
100100
- [新增API时的开发规范](zh/development/developing-api.md)
101101
- [proto文件注释规范](zh/api_reference/comment_spec_of_proto.md)
102-
- [如何基于proto文件生成接口文档](zh/api_reference/how_to_generate_api_doc.md)
102+
- [如何基于proto文件生成代码、接口文档](zh/api_reference/how_to_generate_api_doc.md)
103103
- [Layotto 四大 Github Workflows 说明](zh/development/github-workflows.md)
104104
- [Layotto 命令行工具指南](zh/development/commands.md)
105105
- [发布手册](zh/development/release-guide.md)

‎docs/zh/api_reference/how_to_generate_api_doc.md

+41-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,44 @@
1-
# 如何基于proto文件生成接口文档
1+
# 如何基于proto文件生成代码、接口文档
22

3+
## 如何把 proto 文件编译成`.pb.go`代码
4+
<!-- tabs:start -->
5+
### **Make 命令生成(推荐)**
6+
本地启动 docker 后，在项目根目录下运行：
37

4-
我们可以用[protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) 和docker来生成接口文档，相关命令如下：
5-
(需要在layotto项目下运行命令)
8+
```bash
9+
make proto.code
10+
```
11+
该命令会用 docker 启动 protoc，生成`.pb.go`代码。
12+
13+
这种方式更方便，开发者不需要修改本地 protoc 版本，省去了很多烦恼。
14+
15+
### **手动安装工具**
16+
1. Install protoc version: [v3.17.3](https://github.com/protocolbuffers/protobuf/releases/tag/v3.17.3)
17+
18+
2. Install protoc-gen-go v1.28 and protoc-gen-go-grpc v1.2
19+
20+
3. Generate gRPC `.pb.go` code
21+
22+
```bash
23+
cd spec/proto/runtime/v1
24+
protoc -I. --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=require_unimplemented_servers=false,paths=source_relative *.proto
25+
```
26+
<!-- tabs:end -->
27+
## 如何基于proto文件生成接口文档
28+
29+
我们可以用[protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) 和docker来生成接口文档，相关命令如下：
30+
31+
<!-- tabs:start -->
32+
### **Make 命令生成(推荐)**
33+
本地启动 docker 后，在项目根目录下运行：
34+
35+
```bash
36+
make proto.doc
37+
```
38+
该命令会用 docker 启动 protoc-gen-doc，生成文档
39+
40+
### **用 docker 启动 protoc-gen-doc**
41+
`make proto.doc` 等价于执行以下命令:
642

743
```
844
docker run --rm \
@@ -18,4 +54,5 @@ docker run --rm \
1854
-v $(pwd)/docs/en/api_reference:/out \
1955
-v $(pwd)/spec/proto/runtime/v1:/protos \
2056
pseudomuto/protoc-gen-doc --doc_opt=/protos/template.tmpl,appcallback_v1.md appcallback.proto
21-
```
57+
```
58+
<!-- tabs:end -->

‎make/proto.mk

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Copyright 2021 Layotto Authors
2+
# Licensed under the Apache License, Version 2.0 (the "License");
3+
# you may not use this file except in compliance with the License.
4+
# You may obtain a copy of the License at
5+
6+
# http://www.apache.org/licenses/LICENSE-2.0
7+
8+
# Unless required by applicable law or agreed to in writing, software
9+
# distributed under the License is distributed on an "AS IS" BASIS,
10+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
# See the License for the specific language governing permissions and
12+
# limitations under the License.
13+
14+
.PHONY: proto.gen.doc
15+
proto.gen.doc:
16+
$(DOCKER) run --rm \
17+
-v $(ROOT_DIR)/docs/en/api_reference:/out \
18+
-v $(ROOT_DIR)/spec/proto/runtime/v1:/protos \
19+
pseudomuto/protoc-gen-doc --doc_opt=/protos/template.tmpl,runtime_v1.md runtime.proto
20+
$(DOCKER) run --rm \
21+
-v $(ROOT_DIR)/docs/en/api_reference:/out \
22+
-v $(ROOT_DIR)/spec/proto/runtime/v1:/protos \
23+
pseudomuto/protoc-gen-doc --doc_opt=/protos/template.tmpl,appcallback_v1.md appcallback.proto
24+
25+
.PHONY: proto.gen.init
26+
proto.gen.init:
27+
go install google.golang.org/protobuf/cmd/[email protected]
28+
go install google.golang.org/grpc/cmd/[email protected]
29+
30+
.PHONY: proto.gen.code
31+
proto.gen.code:
32+
$(DOCKER) build -t layotto/protoc $(ROOT_DIR)/docker/proto && \
33+
$(DOCKER) run --rm \
34+
-v $(ROOT_DIR)/spec/proto/runtime/v1:/api/proto \
35+
layotto/protoc

‎spec/proto/runtime/v1/README.md

+2-11
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,3 @@
11

2-
## How to compile these proto files into golang code
3-
```shell
4-
cd ${your PROJECT path}/spec/proto/runtime/v1
5-
protoc -I. --go_out=plugins=grpc,paths=source_relative:. *.proto
6-
```
7-
8-
my protoc version:
9-
```shell
10-
$ protoc --version
11-
libprotoc 3.11.2
12-
```
2+
## How to compile these proto files into golang code and documentation
3+
Please visit https://mosn.io/layotto/#/en/api_reference/how_to_generate_api_doc

0 commit comments

Comments
 (0)