Tuesday, May 31, 2016

Machinekit documentation goes on-line

We are very pleased to announce that the existing machinekit-docs repository is now rendered automatically in html on the www.machinekit.io website.

It was an intense 3 weeks of brain storming, document conversion and creation, struggling with a Jekyll rendering engines, within a docker container, within a Jenkins project deployment server, but now the worst is over and the docs are out there.

Michael Haberler deserves the Order of the Duct Tape 1st Class, for managing to get the whole thing stuck together!

The overriding aim of the work, was to have the whole process be automatically regenerative, any edit to the base repo documents being quickly reflected in the rendered site, no human intervention required, after a pull request is merged.

Currently this takes as little as 2 minutes!

A secondary objective was to make editing and adding to existing documents and contributing new documents as easy as possible.
Only if the user base get actively involved in the documentation, will it transform into the information portal everyone wants.


A site wide search engine, powered by Google.
Already very useful and will expand with time as indexing requests propagate.

An 'Edit this page' link.
This considerably lowers the bar to contribution, requiring only that the user has a GitHub account and user name, to allow them to edit docs and submit the edit as a Pull Request directly via a temporary branch reference.

A SandBox page.
This is for any kind of Machinekit connected contribution.
It could be a HowTo on using a particular board with Machinekit,
a blog type project progress report on a particular machine build,
anything whatsoever.

The document can be created by the same 'Edit this page' link and will be visible in the SandBox from the outset, whilst the maintainers consider how best to incorporate it into the document base.

There is still more work to be done, but already we can see a 100% improvement.

Please get involved and contribute your knowledge for all to benefit from.

Mick, Bas and Michael.