| Re: [iot-wg] documentation example |
Hi,
Do I understand it right, that not even the „sources“ of the documentation are on Github, but only maintained at readme.io? If so, that would also be a no-go for me. A similar approach is https://readthedocs.org/, with the exception that the sources are still on Github and it is only the generated HTML that they host. Some openHAB community member is using it to provide German documentation for openHAB: The sources are maintained as Markdown in Github: https://github.com/mepi0011/openhab.doc Nonetheless, I decided against this approach for Eclipse SmartHome. There, we are maintaining the sources in a subfolder of our main repo as markdown: https://github.com/eclipse/smarthome/tree/master/docs/documentation We have a Maven build, which assembles other sources (e.g. markdown files from within bundles as well as generated JavaDocs and runs Jekyll for generating HTML (in https://github.com/eclipse/smarthome/tree/master/docs). The plan is to do this automatically on any change and push it to the website git repo; currently, this is still done manually. We are quite happy with this approach and at least developer-centric contributors have no issue contributing the documentation through the regular git PR process. Regards, Kai
|