From e1a5c1e5447dfb029ce536020d874b7b9bb44864 Mon Sep 17 00:00:00 2001 From: Denis Laprise Date: Thu, 15 Dec 2022 16:19:44 -0800 Subject: [PATCH 1/2] Add ReStructuredText output --- Makefile | 2 + renderer.go | 7 ++ resources.go | 2 + resources/restructuredtext.tmpl | 119 ++++++++++++++++++++++++++++++++ 4 files changed, 130 insertions(+) create mode 100644 resources/restructuredtext.tmpl diff --git a/Makefile b/Makefile index 5b4d6903..b0628b91 100644 --- a/Makefile +++ b/Makefile @@ -43,6 +43,7 @@ build/examples: bin/protoc build tmp/googleapis examples/proto/*.proto examples/ @$(EXAMPLE_CMD) --doc_opt=html,example.html:Ignore* examples/proto/*.proto @$(EXAMPLE_CMD) --doc_opt=json,example.json:Ignore* examples/proto/*.proto @$(EXAMPLE_CMD) --doc_opt=markdown,example.md:Ignore* examples/proto/*.proto + @$(EXAMPLE_CMD) --doc_opt=restructuredtext,example.rst:Ignore* examples/proto/*.proto @$(EXAMPLE_CMD) --doc_opt=examples/templates/asciidoc.tmpl,example.txt:Ignore* examples/proto/*.proto ##@: Dev @@ -71,6 +72,7 @@ test/docker: bin/protoc tmp/googleapis release/snapshot ## Run the docker e2e te @$(DOCKER_CMD) --doc_opt=html,example.html:Ignore* @$(DOCKER_CMD) --doc_opt=json,example.json:Ignore* @$(DOCKER_CMD) --doc_opt=markdown,example.md:Ignore* + @$(DOCKER_CMD) --doc_opt=restructuredtext,example.md:Ignore* @$(DOCKER_CMD) --doc_opt=/templates/asciidoc.tmpl,example.txt:Ignore* ##@: Release diff --git a/renderer.go b/renderer.go index eba74c5f..8297eaf5 100644 --- a/renderer.go +++ b/renderer.go @@ -20,6 +20,7 @@ const ( RenderTypeHTML RenderTypeJSON RenderTypeMarkdown + RenderTypeReStructuredText ) // NewRenderType creates a RenderType from the supplied string. If the type is not known, (0, error) is returned. It is @@ -34,6 +35,8 @@ func NewRenderType(renderType string) (RenderType, error) { return RenderTypeJSON, nil case "markdown": return RenderTypeMarkdown, nil + case "restructuredtext": + return RenderTypeReStructuredText, nil } return 0, errors.New("Invalid render type") @@ -54,6 +57,8 @@ func (rt RenderType) renderer() (Processor, error) { return new(jsonRenderer), nil case RenderTypeMarkdown: return &htmlRenderer{string(tmpl)}, nil + case RenderTypeReStructuredText: + return &htmlRenderer{string(tmpl)}, nil } return nil, errors.New("Unable to create a processor") @@ -69,6 +74,8 @@ func (rt RenderType) template() ([]byte, error) { return nil, nil case RenderTypeMarkdown: return markdownTmpl, nil + case RenderTypeReStructuredText: + return reStructuredTextTmpl, nil } return nil, errors.New("Couldn't find template for render type") diff --git a/resources.go b/resources.go index cc607412..71d0d4ce 100644 --- a/resources.go +++ b/resources.go @@ -11,6 +11,8 @@ var ( htmlTmpl []byte //go:embed resources/markdown.tmpl markdownTmpl []byte + //go:embed resources/restructuredtext.tmpl + reStructuredTextTmpl []byte //go:embed resources/scalars.json scalarsJSON []byte ) diff --git a/resources/restructuredtext.tmpl b/resources/restructuredtext.tmpl new file mode 100644 index 00000000..f1d67fb8 --- /dev/null +++ b/resources/restructuredtext.tmpl @@ -0,0 +1,119 @@ +###################### +Protocol Documentation +###################### + +{{range .Files}} +{{$file_name := .Name}} + +.. _ref_{{.Name}}: + +{{.Name}} +================================================================== + +{{.Description}} + +{{range .Messages}} + +.. _ref_{{.FullName}}: + +{{.LongName}} +------------------------------------------------------------------ + +{{.Description}} + +{{if .HasFields}} + +.. csv-table:: {{.LongName}} type fields + :header: "Field", "Type", "Label", "Description" + :widths: auto +{{range .Fields }} + "{{.Name}}", ":ref:`ref_{{.FullType}}`", "{{.Label}}", "{{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}}" +{{- end}} +{{end}} + + +{{if .HasExtensions}} + +.. csv-table:: {{.LongName}} type extensions + :header: "Extension", "Type", "Base", "Number", "Description" + :widths: auto +{{range .Extensions }} + "{{.Name}}", "{{.LongType}}", "{{.ContainingLongType}}", "{{.Number}}", "{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}}" +{{- end}} +{{end}} + +{{end}} + +{{range .Enums}} + +.. _ref_{{.FullName}}: + +{{.LongName}} +------------------------------------------------------------------ + +{{.Description}} + +.. csv-table:: Enum {{.LongName}} values + :header: "Name", "Number", "Description" + :widths: auto +{{range .Values }} + "{{.Name}}", "{{.Number}}", "{{nobr .Description}}" +{{- end}} + +{{end}} + +{{if .HasExtensions}} + +.. _ref_{{$file_name}}_extensions: + +File-level Extensions +-------------------------------------------------------------------------------- + +.. csv-table:: {{.Name}} file-level Extensions + :header: "Extension", "Type", "Base", "Number", "Description" + :widths: auto +{{range .Extensions}} + "{{.Name}}", "{{.LongType}}", "{{.ContainingLongType}}", "{{.Number}}", "{{nobr .Description}}{{if .DefaultValue}} Default: `{{.DefaultValue}}`{{end}}" +{{- end}} +{{end}} + +{{range .Services}} + +.. _ref_{{.FullName}}: + +{{.Name}} +------------------------------------------------------------------ + +{{.Description}} + +.. csv-table:: {{.Name}} service methods + :header: "Method Name", "Request Type", "Response Type", "Description" + :widths: auto +{{range .Methods}} + "{{.Name}}", ":ref:`ref_{{.RequestFullType}}`{{if .RequestStreaming}} stream{{end}}", ":ref:`ref_{{.ResponseFullType}}`{{if .ResponseStreaming}} stream{{end}}", "{{nobr .Description}}" +{{- end}} +{{end}} + +{{end}} + +.. _ref_scala_types: + +Scalar Value Types +================== + +{{range .Scalars}} + +.. _ref_{{.ProtoType}}: + +{{.ProtoType}} +----------------------------- + +{{.Notes}} + +.. csv-table:: {{.ProtoType}} language representation + :header: ".proto Type", "C++", "Java", "Python", "Go", "C#", "PHP", "Ruby" + :widths: auto + + "{{.ProtoType}}", "{{.CppType}}", "{{.JavaType}}", "{{.PythonType}}", "{{.GoType}}", "{{.CSharp}}", "{{.PhpType}}", "{{.RubyType}}" + +{{end}} From cfffeab11e0d89c81c18998cf27ce8ef3a6dccc1 Mon Sep 17 00:00:00 2001 From: Denis Laprise Date: Mon, 6 Feb 2023 22:23:20 -0800 Subject: [PATCH 2/2] Update go.mod --- go.mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/go.mod b/go.mod index dc25f7ac..01f2e0f2 100644 --- a/go.mod +++ b/go.mod @@ -1,4 +1,4 @@ -module github.com/pseudomuto/protoc-gen-doc +module github.com/nside/protoc-gen-doc go 1.17