change symlink 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,55 @@ 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/gen/api/docs/payload \
+	$(PROTO_API_DOCS)
+
+proto/gen/api/docs/payload: $(ROOTDIR)/apis/docs/v1/payload.md.tmpl
+
+$(ROOTDIR)/apis/docs/v1/payload.md.tmpl: $(ROOTDIR)/apis/proto/v1/payload/payload.proto $(ROOTDIR)/apis/docs/v1/payload.tmpl
+	@$(call green, "generating payload  v1...")
+	buf generate --template=apis/docs/buf.gen.payload.yaml --path apis/proto/v1/payload/payload.proto
+
+$(ROOTDIR)/apis/docs/v1/%.md: $(ROOTDIR)/apis/proto/v1/vald/%.proto $(ROOTDIR)/apis/docs/v1/payload.md.tmpl $(ROOTDIR)/apis/docs/v1/doc.tmpl
+	@$(call green, "generating documents for API v1...")
+	buf generate --template=apis/docs/buf.gen.tmpl.yaml --path $(subst $(ROOTDIR)/,,$<)
+	cat apis/docs/v1/payload.md.tmpl apis/docs/v1/_doc.md.tmpl > apis/docs/v1/doc.md.tmpl
+	@sleep 1
+	buf generate --template=apis/docs/buf.gen.doc.yaml
+	@sleep 1
+	mv $(ROOTDIR)/apis/docs/v1/doc.md $@
+	rm apis/docs/v1/*doc.md.tmpl
+
 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/buf.gen.doc.yaml

@@ -0,0 +1,27 @@
+#
+# Copyright (C) 2019-2024 vdaas.org vald team <vald@vdaas.org>
+#
+# 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/v1
+    opt: apis/docs/v1/doc.md.tmpl,doc.md

apis/docs/buf.gen.payload.yaml

@@ -0,0 +1,27 @@
+#
+# Copyright (C) 2019-2024 vdaas.org vald team <vald@vdaas.org>
+#
+# 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/v1
+    opt: apis/docs/v1/payload.tmpl,payload.md.tmpl

apis/docs/buf.gen.tmpl.yaml

@@ -0,0 +1,27 @@
+#
+# Copyright (C) 2019-2024 vdaas.org vald team <vald@vdaas.org>
+#
+# 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/v1
+    opt: apis/docs/v1/doc.tmpl,_doc.md.tmpl

apis/docs/v1/doc.tmpl

@@ -0,0 +1,73 @@
+{{- range .Files -}}
+{{- range .Services -}}
+{{- $descs := dict -}}
+{{- range $desc := (splitList "---\n" .Description) -}}
+{{- $lines := splitList "\n" $desc -}}
+{{- $_ := set $descs (first $lines) (join "\n" (rest $lines)) -}}
+{{- end -}}
+# Vald {{ .Name }} APIs
+
+## Overview
+
+{{ if hasKey $descs "Overview" }}{{ $descs.Overview | trim }}{{ end }}
+
+```rpc
+service {{.Name}} {
+
+{{ range .Methods }}  rpc {{ .Name }}({{ .RequestFullType }}) returns ({{ .ResponseFullType }}) {}
+{{ end }}
+}
+```
+
+{{ range .Methods }}
+
+{{- $descs := dict -}}
+{{- range $desc := (splitList "---\n" .Description) -}}
+{{- $lines := splitList "\n" $desc -}}
+{{- $_ := set $descs (first $lines) (join "\n" (rest $lines)) -}}
+{{- end -}}
+## {{ .Name }} RPC
+
+{{ if hasKey $descs "Overview" }}{{ $descs.Overview | trim }}{{ end }}
+
+### Input
+
+- the scheme of `{{ .RequestFullType }}`
+
+  ```rpc
+{{ printf  "{{- template \"scheme:%s\" }}\n" .RequestFullType }}
+  ```
+
+{{ printf  "{{- template \"field:%s\" }}\n" .RequestFullType }}
+
+### Output
+
+- the scheme of `{{ .ResponseFullType }}`
+
+  ```rpc
+{{ printf "{{- template \"scheme:%s\" }}\n" .ResponseFullType }}
+  ```
+
+{{ printf "{{ template \"field:%s\" }}\n" .ResponseFullType }}
+
+{{- if hasKey $descs "Status Code" }}
+### Status Code
+
+| code | description       |
+| :--: | :---------------- |
+{{ pluck "Status Code" $descs | first | trim }}
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+{{ end }}
+
+{{- if hasKey $descs "Troubleshooting" }}
+
+### Troubleshooting
+
+{{ pluck "Troubleshooting" $descs | first | trim }}
+{{ end }}
+
+{{- end -}}
+{{- end -}}
+{{- end -}}