pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.59k stars 462 forks source link

Separate the grpc services and messages in the generated document #465

Closed seeflood closed 2 years ago

seeflood commented 2 years ago

What would you like to be added: Separate the grpc services and messages to make the generated document more readable.

Why is this needed: Currently a generated document with a service and lots of messages is not readable enough. The grpc services and request/response messages are mixed without highlight: image

Can we seperate them to make the doc more readable?

horacimacias commented 2 years ago

you should be able to achieve this by using a custom template. For example, instead of this

## Table of Contents
{{range .Files}}{{$file_name := .Name}}
- [{{.Name}}](#{{.Name}})
  {{- if .Messages }}
  {{range .Messages}}  - [{{.LongName}}](#{{.FullName}})
  {{end}}
  {{- end -}}
  {{- if .Enums }}
  {{range .Enums}}  - [{{.LongName}}](#{{.FullName}})
  {{end}}
  {{- end -}}
  {{- if .Extensions }}
  {{range .Extensions}}  - [File-level Extensions](#{{$file_name}}-extensions)
  {{end}}
  {{- end -}}
  {{- if .Services }}
  {{range .Services}}  - [{{.Name}}](#{{.FullName}})
  {{end}}
  {{- end -}}
{{end}}

just put the services, or all services first then all models, or whatever you find most interesting. In my case I'm putting only the services:

## Table of Contents
{{range .Files}}{{$file_name := .Name}}
- [{{.Name}}](#{{.Name}})
  {{range .Services}}  - [{{.Name}}](#{{.FullName}})
  {{end}}
{{end}}
horacimacias commented 2 years ago

...of course the same applies to the template used for html which looks like is the output you're using

seeflood commented 2 years ago

@horacimacias Thanks!