From 2a1257401fb653eb8f5232554bc64099ab1ecc49 Mon Sep 17 00:00:00 2001
From: Sindre Hansen <sindrehansen92@gmail.com>
Date: Tue, 14 Jan 2025 15:04:47 +0100
Subject: [PATCH] Add custom markdown template

This template does the following:
- Adds an indication that the the field in a message has the `oneof`
property
- Removes the table of contents (Mkdocs automatically adds one for us
when we use this file in the SDK docs)

Other than that the output should be the same as with the standard
template.
---
 markdown.tmpl     | 49 +++++++++++++++++++++++++++++++++++++++++++++++
 protoc-gen-doc.sh |  3 ++-
 2 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 markdown.tmpl

diff --git a/markdown.tmpl b/markdown.tmpl
new file mode 100644
index 00000000..6d719255
--- /dev/null
+++ b/markdown.tmpl
@@ -0,0 +1,49 @@
+# Protocol Documentation
+{{range .Files}}
+{{$file_name := .Name}}
+<a name="{{.Name | anchor}}"></a>
+
+## {{.Name}}
+{{.Description}}
+
+{{range .Messages}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+{{ if .HasFields}}
+| Field | Type | Description |
+| ------| ---- | ----------- |
+{{range .Fields -}}
+| {{if .IsOneof -}}<small>{{if eq .OneofDecl (printf "_%s" .Name)}}<strong>optional</strong>{{else}}<strong>oneof</strong> <code>{{.OneofDecl}}</code>{{end}}</small><br>{{end}}{{.Name}} {{/* noline */ -}}
+| [{{if .IsMap}}map{{else}}{{.Label}} {{end}}{{.LongType}}](#{{.FullType | anchor}}) {{/* noline */ -}}
+| {{if (index .Options "deprecated" | default false)}}**deprecated**<br>{{end}}{{if .Description}}{{.Description | replace "\n" "<br>"}}{{end}} {{/* noline */ -}}
+|
+{{end}}{{/* range .Fields */}}
+{{- end}}{{/* if .HasFields */}}
+{{- end}}{{/* range .Messages */}}
+
+{{range .Enums}}
+<a name="{{.FullName | anchor}}"></a>
+
+### {{.LongName}}
+{{.Description}}
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+  | {{.Name}} | {{.Number}} | {{nobr .Description}} |
+{{end}}
+
+{{end}}
+
+{{- end}}{{/* range .Files */}}
+
+## 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/protoc-gen-doc.sh b/protoc-gen-doc.sh
index 1815fdc7..82b6be4c 100755
--- a/protoc-gen-doc.sh
+++ b/protoc-gen-doc.sh
@@ -4,7 +4,8 @@ echo "Generating Markdown documentation $(pwd)/docs/markdown/protocol.md"
 docker run --rm \
   -v $(pwd)/docs/markdown:/out \
   -v $(pwd)/protobuf_definitions:/protos \
-  pseudomuto/protoc-gen-doc --doc_opt=markdown,protocol.md
+  -v $(pwd)/markdown.tmpl:/markdown.tmpl \
+  pseudomuto/protoc-gen-doc --doc_opt=markdown.tmpl,protocol.md
 
 echo "Generating HTML documentation $(pwd)/docs/html/protocol.html"
 docker run --rm \