docs: prepare template and gen make command

- add markdown simple template
- add Makefile `docgen` command
This commit is contained in:
Evgeniy Kulikov 2019-11-20 16:40:06 +03:00
parent 1cf33e5ffd
commit 04a5b80550
No known key found for this signature in database
GPG key ID: BF6AEE0A2A699BF2
3 changed files with 112 additions and 4 deletions

83
.github/markdown.tmpl vendored Normal file
View file

@ -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}}

View file

@ -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

0
docs/.gitkeep Normal file
View file