Generate single file protocol definition

[webmaster128]

To get an overview about what functionality exists, it would be cool to see a single document defining the protocol.

Features on the whichlist are

1. auto-updating
2. searchable single page (of undefined length)
3. no need to understand golang code
4. no need to understand the weave direcory/files structure
5. no need to understand the current set of backend product names
6. minidocs in form of comments possible but not required
7. one version per bnsd tag

I am thinking about a single merged .proto file for example.

[ethanfrey]

I think this could theoretically be generated by starting with the application-specific TX: https://github.com/iov-one/weave/blob/master/cmd/bnsd/app/codec.proto
and crawling down to all the messages imported by it.

As this is the canonical list of what functionality is available in that app.

[webmaster128]

Alternatively we can merge all .proto files into a single docs page using protoc-gen-doc.

E.g. input: Booking.proto, Customer.proto, Vehicle.proto
Output: https://rawgit.com/pseudomuto/protoc-gen-doc/master/examples/doc/example.html

[ethanfrey]

Great proposal.

To refine this issue, it is adding a script to the Makefile to generate such docs (much as we generate the go code from protobuf now), as well as adding those generated docs to the repo (and maybe CI validates they are up to date on eg. tagged releases)

[ethanfrey]

To make this actionable:

One PR:

• Add make protodocs that compiles with protoc-gen-doc and writes to a well-define location (inside docs?).
• Add description how to run that in the README (for local generation)

Second PR:

• Add a way to upload generated docs and push to a github pages account, so people can view the generated html easily.
• Integrate this into the CI on every master (or tagged?) build. You can use the approach in iov-core as an example to build on.

[ethanfrey]

Closed by #355