Update docs for endpoints

[polydez]

Our docs for various endpoints (in README files) are getting out of date. We should update them. In this issue we can also discuss if there is some automated way to generate endpoint docs for rpc/store/block producer components.

[polydez]

@bobbinth, I've done a small research of available options for documentation generation based on comments in *.proto files. It's not a full list, but there are the most interesting tools I found so far:

1. Simple, but seems to be enough for us: protoc-gen-doc. Simple to use and and open-source (licensed under MIT), supports for custom templates. Generates markdown, as well, as HTML and DocBook. Runs on docker, so it's safe to use in our infrastructure. Example of generated markup: https://github.com/pseudomuto/protoc-gen-doc/blob/master/examples/doc/example.md
2. Generates static HTML: sable-docs. Open-source (MIT). Requires compilation of *.proto files to binary descriptors (*.pb) in order to use. Have Docker images. Example: https://markvincze.github.io/sabledocs/demo/google.datastore.v1.html#service-google.datastore.v1.Datastore
3. Generates MDX docs, which I'm not sure we can fully use in GitBooks: Docusaurus Protobuffet. Open-source, licensed under ISC (MIT equivalent). Doesn't have Docker image, or I haven't found. Requires to first generate JSON files by protobuf, consumes them for building formatted documentation. Seems to not being supported since the last year. Example: https://protobuffet.com/protodocs/protobuffet/example/ad/v1/ads.proto/
4. "Like Swagger but for gRPC" (interactive documentation): gRPC Docs. Open-source (MIT). Requires to first generate JSON files by protoc-gen-doc, uses them for accessing to documentation. Has Docker for hosting the interactive web app. Seems to also not being supported since last year. Live demo doesn't work by now, but there is a screenshot.

Another approach might be to make OpenAPI proxy, which will expose interactive documentation (Swagger).
More info in these articles:

1. https://blainsmith.com/articles/go-grpc-gateway-openapi/
2. https://bbengfort.github.io/2021/01/grpc-openapi-docs/

In my opinion, we should try protoc-gen-doc and generate markdown documentation, hosted on GitBooks. It should be enough for our use-case.

[bobbinth]

Thank you for the comprehensive overview! Agreed that from these protoc-gen-doc seems like the best option and I think Markdown is the way to go. I don't love the format though - but maybe that's OK for now. Ideally, we'd get something like Ethereum docs (source) - but something like this may need to be manually written/maintained.

Maybe the approach could be:

• Instead of maintaining documentation in individual README files, we move it to something like docs directory in the root.
• We use protoc-gen-doc right to generate the foundation of this documentation but we don't set up automated updates.
• Then, over time, we update and complete this documentation manually.

An alternative, of course, is to just do this manually. We don't have a lot of endpoints and they change relatively infrequently. So, documenting them manually and then having a process for keeping them in sync with the code shouldn't be too difficult.