From 04a5b80550190b46167d1dedae070d4ffcaeac2a Mon Sep 17 00:00:00 2001
From: Evgeniy Kulikov <kim@nspcc.ru>
Date: Wed, 20 Nov 2019 16:40:06 +0300
Subject: [PATCH] docs: prepare template and gen make command

- add markdown simple template
- add Makefile `docgen` command
---
 .github/markdown.tmpl | 83 +++++++++++++++++++++++++++++++++++++++++++
 Makefile              | 33 ++++++++++++++---
 docs/.gitkeep         |  0
 3 files changed, 112 insertions(+), 4 deletions(-)
 create mode 100644 .github/markdown.tmpl
 create mode 100644 docs/.gitkeep

diff --git a/.github/markdown.tmpl b/.github/markdown.tmpl
new file mode 100644
index 00000000..f945c137
--- /dev/null
+++ b/.github/markdown.tmpl
@@ -0,0 +1,83 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+{{range .Files}}
+{{$file_name := .Name}}- [{{.Name}}](#{{.Name}})
+{{if .Services}} - Services
+    {{range .Services}}- [{{.Name}}](#{{.FullName}})
+    {{end}}{{end}}
+{{if .Messages}}  - Messages
+    {{range .Messages}}- [{{.LongName}}](#{{.FullName}})
+    {{end}}{{end}}
+{{end}}
+- [Scalar Value Types](#scalar-value-types)
+
+{{range .Files}}
+{{$file_name := .Name}}
+<a name="{{.Name}}"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## {{.Name}}
+{{.Description}}
+
+{{range .Services}}
+
+<a name="{{.FullName}}"></a>
+
+### Service "{{.FullName}}"
+{{.Description}}
+
+```
+{{range .Methods -}}
+  rpc {{.Name}}({{if .RequestStreaming}}stream {{end}}{{.RequestLongType}}) returns ({{if .ResponseStreaming}}stream {{end}}{{.ResponseLongType}});
+{{end}}
+```
+
+{{range .Methods -}}
+#### Method {{.Name}}
+
+{{.Description}}
+
+| Name | Input | Output |
+| ---- | ----- | ------ |
+| {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}) | [{{.ResponseLongType}}](#{{.ResponseFullType}}) |
+{{end}}{{end}} <!-- end services -->
+
+{{range .Messages}}
+<a name="{{.FullName}}"></a>
+
+### Message {{.LongName}}
+{{.Description}}
+
+{{if .HasFields}}
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+{{range .Fields -}}
+  | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} |
+{{end}}{{end}}
+{{end}} <!-- end messages -->
+
+{{range .Enums}}
+<a name="{{.FullName}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+  | {{.Name}} | {{.Number}} | {{nobr .Description}} |
+{{end}}
+
+{{end}} <!-- end enums -->
+
+{{end}}
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ Type | Java Type | Python Type |
+| ----------- | ----- | -------- | --------- | ----------- |
+{{range .Scalars -}}
+  | <a name="{{.ProtoType}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} |
+{{end}}
diff --git a/Makefile b/Makefile
index c17477a8..64b09397 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,26 @@
+B=\033[0;1m
+G=\033[0;92m
+R=\033[0m
+
+# Reformat code
+format:
+	@[ ! -z `which goimports` ] || (echo "install goimports" && exit 2)
+	@for f in `find . -type f -name '*.go' -not -path './vendor/*' -not -name '*.pb.go' -prune`; do \
+		echo "${B}${G}⇒ Processing $$f ${R}"; \
+		goimports -w $$f; \
+	done
+
+# Regenerate documentation for protot files:
+docgen:
+	@for f in `find . -type f -name '*.proto' -not -path './vendor/*' -exec dirname {} \; | sort -u `; do \
+		echo "${B}${G}⇒ Documentation for $$(basename $$f) ${R}"; \
+		protoc \
+			--doc_opt=.github/markdown.tmpl,$${f}.md \
+			--proto_path=.:./vendor:/usr/local/include \
+			--doc_out=docs/ $${f}/*.proto; \
+	done
+
+# Regenerate proto files:
 protoc:
 	@go mod tidy -v
 	@go mod vendor
@@ -6,7 +29,9 @@ protoc:
 	# Install specific version for protobuf lib
 	@go list -f '{{.Path}}/...@{{.Version}}' -m  github.com/golang/protobuf | xargs go get -v
 	# Protoc generate
-	@find . -type f -name '*.proto' -not -path './vendor/*' \
-		-exec protoc \
-		--proto_path=.:./vendor \
-		--gofast_out=plugins=grpc,paths=source_relative:. '{}' \;
+	@for f in `find . -type f -name '*.proto' -not -path './vendor/*'`; do \
+		echo "${B}${G}⇒ Processing $$f ${R}"; \
+		protoc \
+			--proto_path=.:./vendor:/usr/local/include \
+			--gofast_out=plugins=grpc,paths=source_relative:. $$f; \
+	done
diff --git a/docs/.gitkeep b/docs/.gitkeep
new file mode 100644
index 00000000..e69de29b