feat: generate markdown doc from protobuf

.circleci/config.yml

@@ -57,7 +57,7 @@ jobs:
   go-generate:
     working_directory: /go/src/berty.tech
     docker:
-      - image: bertytech/protoc:20
+      - image: bertytech/protoc:21
     environment:
       - GO111MODULE=on
     steps:
@@ -74,7 +74,7 @@ jobs:
   js-generate:
     working_directory: /go/src/berty.tech
     docker:
-      - image: bertytech/protoc:20
+      - image: bertytech/protoc:21
     steps:
       - checkout
       - js_restore_cache
@@ -88,7 +88,7 @@ jobs:
   js-lint:
     working_directory: /go/src/berty.tech
     docker:
-      - image: bertytech/protoc:20
+      - image: bertytech/protoc:21
     steps:
       - checkout
       - js_restore_cache

.gitattributes

@@ -8,7 +8,6 @@ client/common/openssl/built/* linguist-vendored
 gen.sum linguist-generated
 go.mod linguist-generated
 go.sum linguist-generated
-*.swagger.json linguist-generated
 *.gen.go linguist-generated
 *.gen.yml linguist-generated
 *.gen.graphql linguist-generated
@@ -19,6 +18,7 @@ client/react-native/common/schema.graphql linguist-generated
 *.pb.d.ts linguist-generated
 yarn.lock linguist-generated
 *.gen.js linguist-generated
+docs/*/api.md linguist-generated
 
 # Reduce conflicts on markdown files
 *.md merge=union

api/bertyprotocol.proto

@@ -2,7 +2,6 @@ syntax = "proto3";
 
 package berty.protocol;
 
-import "google/api/annotations.proto";
 import "github.com/gogo/protobuf/gogoproto/gogo.proto";
 import "github.com/golang/protobuf/ptypes/timestamp/timestamp.proto";
 
@@ -12,7 +11,7 @@ option go_package = "berty.tech/go/pkg/bertyprotocol";
 // Each Berty Protocol Instance is considered as a Berty device and is associated with a Berty user.
 service ProtocolService {
   // InstanceExportData exports instance data
-  rpc InstanceExportData (InstanceExportData.Request) returns (InstanceExportData.Reply) { option (google.api.http) = {post: "/instance/export-data"}; };
+  rpc InstanceExportData (InstanceExportData.Request) returns (InstanceExportData.Reply);
 
   // InstanceGetConfiguration gets current configuration of this protocol instance
   rpc InstanceGetConfiguration (InstanceGetConfiguration.Request) returns (InstanceGetConfiguration.Reply);

docs/Makefile

@@ -2,13 +2,15 @@
 ## Code gen
 ##
 
-PROTOS_SRC := $(wildcard ../api/*.proto) # $(wildcard ../api/go-internal/*.proto) $(wildcard ../api/js-internal/*.proto)
+PROTOS_SRC := $(wildcard ../api/*.proto)
 GEN_SRC := $(PROTOS_SRC) Makefile
 GEN_SUM := gen.sum
 
+all: generate
+
 .PHONY: clean
 clean:
-	rm -f gen.sum $(wildcard *.swagger.json) $(wildcard *.swagger.yaml)
+	rm -f gen.sum $(wildcard */*.md.tmp)
 
 .PHONY: generate
 generate: gen.sum
@@ -23,14 +25,18 @@ $(GEN_SUM): $(GEN_SRC)
 	    --workdir="/go/src/berty.tech/docs" \
 	    --entrypoint="sh" \
 	    --rm \
-	    bertytech/protoc:20 \
+	    bertytech/protoc:21 \
 	    -xec 'make generate_local' \
 	)
 
+PROTOC_OPTS = -I ../go/vendor/github.com/grpc-ecosystem/grpc-gateway:../api:../go/vendor:/protobuf
 .PHONY: generate_local
 generate_local:
-	protoc -I ../api:../go/vendor:/protobuf --swagger_out=logtostderr=true:./protocol ../api/bertyprotocol.proto
-	protoc -I ../api:../go/vendor:/protobuf --swagger_out=logtostderr=true:./chat ../api/chatmodel.proto
-	protoc -I ../api:../go/vendor:/protobuf --swagger_out=logtostderr=true:./chat ../api/bertychat.proto
+	protoc $(PROTOC_OPTS) --doc_out=./protocol --doc_opt=markdown,api.md.tmp ../api/bertyprotocol.proto
+	protoc $(PROTOC_OPTS) --doc_out=./chat --doc_opt=markdown,api.md.tmp ../api/bertychat.proto ../api/chatmodel.proto
+	@# repace multiple empty lines with one
+	cat protocol/api.md.tmp | sed '/^$$/N;/^\n$$/D' > protocol/api.md
+	cat chat/api.md.tmp     | sed '/^$$/N;/^\n$$/D' > chat/api.md
+	rm -f */*.md.tmp
 	shasum $(GEN_SRC) | sort -k 2 > $(GEN_SUM).tmp
 	mv $(GEN_SUM).tmp $(GEN_SUM)