automated build of protobuf documentation missing

[ArcEye]

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:

• update the protobuf git subtree
• run the protobuf-docs make target which does the protoc-gen-docs job
• run the website build

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

[ArcEye]

See https://github.com/machinekit/machinekit-cnc/issues/41 for full text, this is a copy header only.