init auto generatation for API documents

Makefile

@@ -153,6 +153,8 @@ PROTOS_V1 := $(eval PROTOS_V1 := $(filter apis/proto/v1/%.proto,$(PROTOS)))$(PRO
 PBGOS = $(PROTOS:apis/proto/%.proto=apis/grpc/%.pb.go)
 SWAGGERS = $(PROTOS:apis/proto/%.proto=apis/swagger/%.swagger.json)
 PBDOCS = $(ROOTDIR)/apis/docs/v1/docs.md
+PROTO_APIS := $(eval PROTO_APIS := $(filter $(ROOTDIR)/apis/proto/v1/vald/%.proto,$(PROTOS)))$(PROTO_APIS)
+PROTO_API_DOCS := $(PROTO_APIS:$(ROOTDIR)/apis/proto/v1/vald/%.proto=$(ROOTDIR)/apis/docs/v1/%.md)
 
 LDFLAGS = -static -fPIC -pthread -std=gnu++23 -lstdc++ -lm -z relro -z now -flto=auto -march=native -mtune=native -fno-plt -Ofast -fvisibility=hidden -ffp-contract=fast -fomit-frame-pointer -fmerge-all-constants -funroll-loops -falign-functions=32 -ffunction-sections -fdata-sections
 

Makefile.d/proto.mk

@@ -17,7 +17,8 @@
 ## build protobufs
 proto/all: \
 	proto/deps \
-	proto/gen
+	proto/gen/code \
+	proto/gen/api/docs
 
 .PHONY: proto/clean
 ## clean proto artifacts
@@ -34,30 +35,44 @@ proto/paths/print:
 .PHONY: proto/deps
 ## install protobuf dependencies
 proto/deps: \
-	$(GOBIN)/buf
+	$(GOBIN)/buf \
+	$(GOBIN)/protoc-gen-doc
 
 .PHONY: proto/clean/deps
 ## uninstall all protobuf dependencies
 proto/clean/deps:
 	rm -rf $(GOBIN)/buf
+	rm -rf $(GOBIN)/protoc-gen-doc
 
 $(GOBIN)/buf:
 	$(call go-install, github.com/bufbuild/buf/cmd/buf)
 
+$(GOBIN)/protoc-gen-doc:
+	$(call go-install, github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc)
+
 $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto:
 	curl -fsSL https://raw.githubusercontent.com/googleapis/googleapis/master/google/rpc/error_details.proto -o $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto
 	sed  -i -e "s/package google.rpc/package rpc.v1/" $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto
 	sed  -i -e "s%google.golang.org/genproto/googleapis/rpc/errdetails;errdetails%$(GOPKG)/apis/grpc/v1/rpc/errdetails%" $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto
 	sed  -i -e "s/com.google.rpc/org.vdaas.vald.api.v1.rpc/" $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto
 
-proto/gen: \
+proto/gen/code: \
 	$(PROTOS) \
 	proto/deps
 	@$(call green, "generating pb.go and swagger.json files and documents for API v1...")
 	buf format -w
 	buf generate
 	make proto/replace
 
+proto/gen/api/docs: $(PROTO_API_DOCS)
+
+$(ROOTDIR)/apis/docs/v1/%.md: $(ROOTDIR)/apis/proto/v1/vald/%.proto
+	@$(call green, "generating documents for API v1...")
+	buf generate --template=buf.gen.doc.yaml --path $(subst $(ROOTDIR)/,,$<)
+	@sleep 1
+	mv $(ROOTDIR)/apis/docs/v1/vald/tmp.md $@
+	rmdir $(ROOTDIR)/apis/docs/v1/vald
+
 proto/replace:
 	find $(ROOTDIR)/apis/grpc/* -name '*.go' | xargs -P$(CORES) sed -i -E "s%google.golang.org/grpc/codes%$(GOPKG)/internal/net/grpc/codes%g"
 	find $(ROOTDIR)/apis/grpc/* -name '*.go' | xargs -P$(CORES) sed -i -E "s%google.golang.org/grpc/status%$(GOPKG)/internal/net/grpc/status%g"

apis/docs/v1/docs.md.tmpl

@@ -0,0 +1,19 @@
+{{range .Files}}
+
+# {{.Name}} document
+
+## Table of Contents
+{{if .HasServices}}
+- Services
+{{range .Services}}
+  - [{{.Name}}]({{.Name}})
+{{end}}
+{{end}}
+
+{{if .HasMessages}}
+{{end}}
+
+{{if .HasEnums}}
+{{end}}
+
+{{end}}

buf.gen.doc.yaml

@@ -0,0 +1,27 @@
+#
+# Copyright (C) 2019-2024 vdaas.org vald team <[email protected]>
+#
+# 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
+#
+#    https://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.
+#
+version: v2
+managed:
+  disable:
+    - file_option: go_package
+      module: buf.build/googleapis/googleapis
+  override:
+    - file_option: go_package_prefix
+      value: github.com/vdaas/vald/apis/grpc
+plugins:
+  - local: protoc-gen-doc
+    out: apis/docs
+    opt: apis/docs/v1/docs.md.tmpl,tmp.md,source_relative