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 + + +## 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}} + +

Top

+ +## {{.Name}} +{{.Description}} + +{{range .Services}} + + + +### 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}} + +{{range .Messages}} + + +### 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}} + +{{range .Enums}} + + +### {{.LongName}} +{{.Description}} + +| Name | Number | Description | +| ---- | ------ | ----------- | +{{range .Values -}} + | {{.Name}} | {{.Number}} | {{nobr .Description}} | +{{end}} + +{{end}} + +{{end}} + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +{{range .Scalars -}} + | {{.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