feat(docs) prepare api docs generation

api/Makefile

@@ -28,13 +28,16 @@ UDPA_LATEST_VERSION := master
 UDPA_ACTUAL_VERSION := $(shell $(call go_mod_latest_version,github.com/cncf,udpa))
 GOOGLEAPIS_LATEST_VERSION := master
 GOOGLEAPIS_ACTUAL_VERSION := $(shell $(call go_mod_latest_version,github.com/googleapis,googleapis))
+KUMADOC_VERSION := v0.1.5
+KUMADOC_ACTUAL_VERSION := $(shell $(call go_mod_latest_version,github.com/kumahq,protoc-gen-kumadoc))
 
 protoc_search_go_packages := \
 	github.com/golang/protobuf@$(GOLANG_PROTOBUF_VERSION) \
 	github.com/envoyproxy/protoc-gen-validate@$(PROTOC_PGV_VERSION) \
 	github.com/envoyproxy/data-plane-api@$(DATAPLANE_API_ACTUAL_VERSION) \
 	github.com/cncf/udpa@$(UDPA_ACTUAL_VERSION) \
-	github.com/googleapis/googleapis@$(GOOGLEAPIS_ACTUAL_VERSION)
+	github.com/googleapis/googleapis@$(GOOGLEAPIS_ACTUAL_VERSION) \
+	github.com/kumahq/protoc-gen-kumadoc@$(KUMADOC_ACTUAL_VERSION)/proto
 
 protoc_search_go_paths := $(foreach go_package,$(protoc_search_go_packages),--proto_path=$(GOPATH_DIR)/pkg/mod/$(go_package))
 
@@ -51,16 +54,30 @@ comma := ,
 empty:=
 space := $(empty) $(empty)
 
+DOCS_OUTPUT_PATH ?= .
+
+additional_params ?=
+
+ifdef PLUGIN
+	additional_params += --plugin=protoc-gen-kumadoc=$(PLUGIN)
+endif
+
 go_mapping_with_spaces := $(foreach entry,$(go_import_mapping_entries),M$(entry),)
 go_mapping := $(subst $(space),$(empty),$(go_mapping_with_spaces))
 
-PROTOC_GO := protoc \
+PROTOC := protoc \
 	--proto_path=$(PROTOBUF_WKT_DIR)/include \
 	--proto_path=. \
-	$(protoc_search_go_paths) \
+	$(protoc_search_go_paths)
+
+PROTOC_GO := $(PROTOC) \
 	--go_opt=paths=source_relative \
 	--go_out=plugins=grpc,$(go_mapping):.
 
+PROTOC_KUMADOC := $(PROTOC) \
+	--kumadoc_out=$(DOCS_OUTPUT_PATH) \
+	$(additional_params)
+
 PROTOC_OS=unknown
 PROTOC_ARCH=$(shell uname -m)
 
@@ -76,7 +93,7 @@ endif
 help: ## Display this help screen
 	@grep -h -E '^[a-zA-Z_/-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
-dev/tools: install/protoc install/protobuf-wellknown-types install/data-plane-api install/protoc-gen-go install/protoc-gen-validate ## Install development tools
+dev/tools: install/protoc install/protobuf-wellknown-types install/data-plane-api install/protoc-gen-go install/protoc-gen-validate install/protoc-gen-kumadoc ## Install development tools
 
 install/protoc:
 	@if [ -e $(PROTOC_PATH) ]; then echo "Protoc $$( $(PROTOC_PATH) --version ) is already installed at $(PROTOC_PATH)" ; fi
@@ -109,6 +126,9 @@ install/protobuf-wellknown-types:
 install/protoc-gen-go:
 	go get github.com/golang/protobuf/protoc-gen-go@$(GOLANG_PROTOBUF_VERSION)
 
+install/protoc-gen-kumadoc:
+	go get github.com/kumahq/protoc-gen-kumadoc@$(KUMADOC_VERSION)
+
 install/protoc-gen-validate:
 	go get github.com/envoyproxy/protoc-gen-validate@$(PROTOC_PGV_VERSION)
 
@@ -143,3 +163,6 @@ test: ## Run tests
 
 check: generate build test ## Verify that auto-generated code is up-to-date
 	git diff --quiet || test $$(git diff --name-only | grep -v -e 'go.mod$$' -e 'go.sum$$' | wc -l) -eq 0 || ( echo "The following changes (result of code generators) have been detected:" && git --no-pager diff && false ) # fail if Git working tree is dirty
+
+generate/docs:
+	$(PROTOC_KUMADOC) mesh/v1alpha1/*.proto

api/mesh/v1alpha1/circuit_breaker.proto

@@ -7,6 +7,13 @@ option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 import "mesh/v1alpha1/selector.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "CircuitBreaker",
+  file_name : "circuit-breaker"
+};
 
 // CircuitBreaker defines circuit breaking policy for dataplane's outbound
 message CircuitBreaker {

api/mesh/v1alpha1/externalservice.proto

@@ -7,6 +7,13 @@ option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 import "validate/validate.proto";
 
 import "system/v1alpha1/datasource.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "ExternalService",
+  file_name : "external-service"
+};
 
 // ExternalService defines configuration of the externaly accessible service
 message ExternalService {

api/mesh/v1alpha1/fault_injection.proto

@@ -7,6 +7,13 @@ option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 import "google/protobuf/duration.proto";
 import "mesh/v1alpha1/selector.proto";
 import "google/protobuf/wrappers.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "FaultInjection",
+  file_name : "fault-injection"
+};
 
 // FaultInjection defines the configuration of faults between dataplanes.
 message FaultInjection {

api/mesh/v1alpha1/health_check.proto

@@ -9,6 +9,13 @@ import "mesh/v1alpha1/selector.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 import "validate/validate.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "HealthCheck",
+  file_name : "health-check"
+};
 
 // HealthCheck defines configuration for health checking.
 message HealthCheck {

api/mesh/v1alpha1/proxy_template.proto

@@ -5,6 +5,13 @@ package kuma.mesh.v1alpha1;
 option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 
 import "mesh/v1alpha1/selector.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "ProxyTemplate",
+  file_name : "proxy-template"
+};
 
 // ProxyTemplate defines the desired state of ProxyTemplate
 message ProxyTemplate {

api/mesh/v1alpha1/retry.proto

@@ -9,6 +9,13 @@ import "mesh/v1alpha1/selector.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
 import "validate/validate.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "Retry",
+  file_name : "retry"
+};
 
 message Retry {
   // List of selectors to match dataplanes that retry policy should be

api/mesh/v1alpha1/timeout.proto

@@ -6,6 +6,13 @@ option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 
 import "mesh/v1alpha1/selector.proto";
 import "google/protobuf/duration.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "Timeout",
+  file_name : "timeout"
+};
 
 message Timeout {
 

api/mesh/v1alpha1/traffic_log.proto

@@ -5,6 +5,13 @@ package kuma.mesh.v1alpha1;
 option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 
 import "mesh/v1alpha1/selector.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "TrafficLog",
+  file_name : "traffic-log"
+};
 
 // TrafficLog defines log for traffic between dataplanes.
 message TrafficLog {

api/mesh/v1alpha1/traffic_permission.proto

@@ -5,6 +5,13 @@ package kuma.mesh.v1alpha1;
 option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 
 import "mesh/v1alpha1/selector.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "TrafficPermissions",
+  file_name : "traffic-permissions"
+};
 
 // TrafficPermission defines permission for traffic between dataplanes.
 message TrafficPermission {

api/mesh/v1alpha1/traffic_route.proto

@@ -6,6 +6,13 @@ option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 
 import "mesh/v1alpha1/selector.proto";
 import "validate/validate.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "TrafficRoute",
+  file_name : "traffic-route"
+};
 
 // TrafficRoute defines routing rules for L4 traffic.
 message TrafficRoute {

api/mesh/v1alpha1/traffic_trace.proto

@@ -5,6 +5,13 @@ package kuma.mesh.v1alpha1;
 option go_package = "github.com/kumahq/kuma/api/mesh/v1alpha1";
 
 import "mesh/v1alpha1/selector.proto";
+import "config.proto";
+
+option (doc.config) = {
+  type : Policy,
+  name : "TrafficTrace",
+  file_name : "traffic-trace"
+};
 
 // TrafficTrace defines trace configuration for selected dataplanes.
 message TrafficTrace {

go.mod

@@ -4,7 +4,6 @@ go 1.15
 
 require (
 	cirello.io/pglock v1.8.0
-	github.com/Masterminds/semver v1.5.0 // indirect
 	github.com/Masterminds/sprig v2.22.0+incompatible
 	github.com/Nordix/simple-ipam v1.0.0
 	github.com/asaskevich/govalidator v0.0.0-20200428143746-21a406dcc535

go.sum

@@ -110,9 +110,8 @@ github.com/Knetic/govaluate v3.0.1-0.20171022003610-9aa49832a739+incompatible/go
 github.com/MakeNowJust/heredoc v0.0.0-20170808103936-bb23615498cd/go.mod h1:64YHyfSL2R96J44Nlwm39UHepQbyR5q10x7iYa1ks2E=
 github.com/Masterminds/goutils v1.1.0 h1:zukEsf/1JZwCMgHiK3GZftabmxiCw4apj3a28RPBiVg=
 github.com/Masterminds/goutils v1.1.0/go.mod h1:8cTjp+g8YejhMuvIA5y2vz3BpJxksy863GQaJW2MFNU=
+github.com/Masterminds/semver v1.4.2 h1:WBLTQ37jOCzSLtXNdoo8bNM8876KhNqOKvrlGITgsTc=
 github.com/Masterminds/semver v1.4.2/go.mod h1:MB6lktGJrhw8PrUyiEoblNEGEQ+RzHPF078ddwwvV3Y=
-github.com/Masterminds/semver v1.5.0 h1:H65muMkzWKEuNDnfl9d70GUjFniHKHRbFPGBuZ3QEww=
-github.com/Masterminds/semver v1.5.0/go.mod h1:MB6lktGJrhw8PrUyiEoblNEGEQ+RzHPF078ddwwvV3Y=
 github.com/Masterminds/semver/v3 v3.1.0 h1:Y2lUDsFKVRSYGojLJ1yLxSXdMmMYTYls0rCvoqmMUQk=
 github.com/Masterminds/semver/v3 v3.1.0/go.mod h1:VPu/7SZ7ePZ3QOrcuXROw5FAcLl4a0cBrbBpGY/8hQs=
 github.com/Masterminds/sprig v2.20.0+incompatible/go.mod h1:y6hNFY5UBTIWBxnzTeuNhlNS5hqE0NB0E6fgfo2Br3o=