automated build of protobuf documentation missing

Issue by mhaberler Thu Jun 16 06:41:49 2016 Originally opened as https://github.com/machinekit/machinekit/issues/970

this is an anchor issue for integrating the machinekit protobuf docs into the website

it's a sub-project of https://github.com/machinekit/machinekit/issues/924 which is getting a tad long, so let's focus related work here

my overall idea is:

the protobuf definitions are all important and need to be documented - ideally the same way like all the rest, 'Edit this page' link inlcuded on a per-proto-file basis
there is a neat tool - protoc-gen-docs - which aids in generating docs from proto files - see input example and resulting output
protoc-gen-docs is already part of the jekyll website build container and running on jenkins.machinekit.io

So to integrate the protobuf docs build into the website I guess we need to:

add the protobuf repo into the machinekit-docs repo as a subtree (just as with mk/mk - no magic, explained here)
add a Makefile step which runs protoc-gen-docs on the proto files, generating asciidoc; that is in place already and just needs to be integrated, and proper place for the output found
adapt the Mustache template to output proper asciidoc - this file needs translating from markdown to asciidoc syntax ; the current output formats do not include asciidoc yet
think through how 'Edit this proto file' links can be massaged into the output
link the protobuf docs page in a warm place (likely near manual pages)

The build process then would be like so:

I will take care of the jenkins work to achieve that, but a sharing work with the template work would be great

machinekit / machinekit-hal