gRPC documentation

[b00f]

Okay, right now, our rGRC APIs are almost becoming stable, and they won't change daily. It is time to think about how to create documentation for the APIs. The best way seems to be inline documentation in the proto file. There is no other solution, like a side YAML file for generating documents. Let's look at where we need the documentation:

1. The documentation should be added to Swagger API. This can be done automatically once we generate the proto.
2. The generated files should be documented; this is also done automatically.
3. Adding helper strings to the pactus-ctl binary. This needs to be examined.
4. Documentation for publishing on the website.

There is an issue regarding generating documents to publish on the pactus.org website: here.

There are some tools that can help us generate static documents for the gRPC API; here is what I found so far:

• https://github.com/markvincze/sabledocs
• https://blog.gendocu.com/posts/documenting-grpc/

[amirvalhalla]

@b00f
Both packages utilize protoc. Based on our previous discussion, do you agree with using buf? If so, should we explore a way to incorporate them into buf?

[b00f]

Yes, if we can use only buf is really good.

[b00f]

Options we have:

• https://github.com/pseudomuto/protoc-gen-doc
• https://github.com/gendocu-com/grpc-docs
• https://github.com/markvincze/sabledocs