feat protodocs: add template, use new template

Our own template with YFM support.
Also, for debugging, use it in Fleet Tracking System documentation

Testing: none required, just docs
commit_hash:94e983300b5c5d227f0dc3d3c0069c3d2a2bd5e0

3 files changed, 116 insertions, 2 deletions

diff --git a/build/conf/proto.conf b/build/conf/proto.conf
index e268dc42369..48904c37a15 100644
--- a/build/conf/proto.conf
+++ b/build/conf/proto.conf
@@ -394,7 +394,7 @@ macro _GO_PROTO_CMD(File) {
 
 # tag:proto tag:docs-specific
 macro _DOCS_PROTO_CMD(File) {
-    .CMD=${cwd;rootdir;input:File} $YMAKE_PYTHON3 ${input:"build/scripts/docs_proto_wrapper.py"} --docs-output ${output;norel;nopath;suf=.md;noext:File} -- $PROTOC -I=./$PROTO_NAMESPACE -I=$ARCADIA_ROOT/$PROTO_NAMESPACE ${pre=-I=:_PROTO__INCLUDE} -I=$ARCADIA_BUILD_ROOT -I=$PROTOBUF_INCLUDE_PATH $_PROTOC_FLAGS --plugin=protoc-gen-doc=${tool:"vendor/github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc"} ${input;rootrel:File} ${hide:PROTO_FAKEID} ${hide;kv:"p PD"} ${hide;kv:"pc yellow"}
+    .CMD=${cwd;rootdir;input:File} $YMAKE_PYTHON3 ${input:"build/scripts/docs_proto_wrapper.py"} --docs-output ${output;norel;nopath;suf=.md;noext:File} --template ${input:"build/scripts/docs_proto_markdown.tmpl"} -- $PROTOC -I=./$PROTO_NAMESPACE -I=$ARCADIA_ROOT/$PROTO_NAMESPACE ${pre=-I=:_PROTO__INCLUDE} -I=$ARCADIA_BUILD_ROOT -I=$PROTOBUF_INCLUDE_PATH $_PROTOC_FLAGS --plugin=protoc-gen-doc=${tool:"vendor/github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc"} ${input;rootrel:File} ${hide:PROTO_FAKEID} ${hide;kv:"p PD"} ${hide;kv:"pc yellow"}
 }
 
 # tag:proto
diff --git a/build/scripts/docs_proto_markdown.tmpl b/build/scripts/docs_proto_markdown.tmpl
new file mode 100644
index 00000000000..87a94ce8c4e
--- /dev/null
+++ b/build/scripts/docs_proto_markdown.tmpl
@@ -0,0 +1,112 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+{{range .Files}}
+{{$file_name := .Name}}- [{{.Name}}](#{{.Name | anchor}})
+  {{- if .Messages }}
+  {{range .Messages}}  - [{{.LongName}}](#{{.FullName | anchor}})
+  {{end}}
+  {{- end -}}
+  {{- if .Enums }}
+  {{range .Enums}}  - [{{.LongName}}](#{{.FullName | anchor}})
+  {{end}}
+  {{- end -}}
+  {{- if .Extensions }}
+  {{range .Extensions}}  - [File-level Extensions](#{{$file_name | anchor}}-extensions)
+  {{end}}
+  {{- end -}}
+  {{- if .Services }}
+  {{range .Services}}  - [{{.Name}}](#{{.FullName | anchor}})
+  {{end}}
+  {{- end -}}
+{{end}}
+- [Scalar Value Types](#scalar-value-types)
+
+{{range .Files}}
+{{$file_name := .Name}}
+<a name="{{.Name | anchor}}"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## {{.Name}} {{ .Name | anchor}}
+{{.Description}}
+
+{{range .Messages}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.LongName}} {{"{#"}}{{ .FullName | anchor}}{{"}"}}
+{{.Description}}
+
+{{if .HasFields}}
+#|
+|| *Field* | *Type* | *Label* | *Description* ||
+{{range .Fields -}}
+  || {{.Name}} | [{{.LongType}}](#{{.FullType | anchor}}) | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} ||
+{{end}}
+|#
+{{end}}
+
+{{if .HasExtensions}}
+#{
+|| *Extension* | *Type* | *Base* | *Number* | *Description* ||
+{{range .Extensions -}}
+  || {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} ||
+{{end}}
+|#
+{{end}}
+
+{{end}} <!-- end messages -->
+
+{{range .Enums}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+#|
+|| *Name* | *Number* | *Description* ||
+{{range .Values -}}
+  || {{.Name}} | {{.Number}} | {{nobr .Description}} ||
+{{end}}
+|#
+
+{{end}} <!-- end enums -->
+
+{{if .HasExtensions}}
+<a name="{{$file_name | anchor}}-extensions"></a>
+
+### File-level Extensions
+
+#|
+|| *Extension* | *Type* | *Base* | *Number* | *Description* ||
+{{range .Extensions -}}
+  || {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{nobr .Description}}{{if .DefaultValue}} Default: `{{.DefaultValue}}`{{end}} ||
+{{end}}
+|#
+{{end}} <!-- end HasExtensions -->
+
+{{range .Services}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.Name}}
+{{.Description}}
+
+#|
+|| *Method Name* | *Request Type* | *Response Type* | *Description* ||
+{{range .Methods -}}
+  || {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType | anchor}}){{if .RequestStreaming}} stream{{end}} | [{{.ResponseLongType}}](#{{.ResponseFullType | anchor}}){{if .ResponseStreaming}} stream{{end}} | {{nobr .Description }}  ||
+{{end}}
+|#
+
+{{end}} <!-- end services -->
+
+{{end}}
+
+## Scalar Value Types
+
+#|
+|| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby ||
+{{range .Scalars -}}
+  || <a name="{{.ProtoType | anchor}}" /> {{.ProtoType}} | {{.Notes}} | {{.CppType}} | {{.JavaType}} | {{.PythonType}} | {{.GoType}} | {{.CSharp}} | {{.PhpType}} | {{.RubyType}} ||
+{{end}}
+|#
diff --git a/build/scripts/docs_proto_wrapper.py b/build/scripts/docs_proto_wrapper.py
index 71cb2124a2e..75ae8076129 100644
--- a/build/scripts/docs_proto_wrapper.py
+++ b/build/scripts/docs_proto_wrapper.py
@@ -7,6 +7,7 @@ import pathlib
 def parse_args():
     parser = argparse.ArgumentParser()
     parser.add_argument('--docs-output', required=True)
+    parser.add_argument('--template', required=True)
     parser.add_argument('args', nargs='+')
 
     return parser.parse_args()
@@ -19,7 +20,8 @@ def main(args):
     # --doc_opt=markdon,TARGET_FILE_NAME
 
     target_file = pathlib.Path(args.docs_output)
-    cmd.append(f'--doc_opt=markdown,{target_file.name}')
+    target_template = pathlib.Path(args.template)
+    cmd.append(f'--doc_opt={target_template},{target_file.name}')
     cmd.append(f'--doc_out={target_file.parent}')
 
     try: