Ok, I again spent some hours on it, but struggled a lot.
I had to learn that Jekyll on Github Pages does not support symlinks (despite the fact that Jekyll DOES support them locally, so I only noticed after pushing the stuff to Github 
).
So in order to aggregate documentation (mainly of add-ons) from other repositories, I have now added a pom.xml which copies the required files from the submodule repos to their place in the documentation. We will have to set this up as a regular Maven build, which automatically commits the changes.
@bipphilippe The currentl documentation is what already existed in the openhab-distro repository. I donât mind if you do heavy refactoring of it, just a few remarks from me:
- I have created two parts:
- one âtutorialâ/âgetting startedâ, which is the section for beginners to find their way - this should imho mainly be filled with the content you have started in your git book.
- one âreference documentationâ, which should nicely structure all the different features of openHAB to be a point of reference to look up stuff. This part gathers the content from the different repos and we should try to reuse as much as possible. For the general concepts, we should try to document as much as possible in Eclipse SmartHome and write that in a way that we can include it without changes in the openHAB documentation.
- Most binding readmes are still lacking the frontmatter header, so that Jekyll does not process them. I am wondering if we should add this header automatically when copying the files through Maven, instead of adding it to the sources directly.
- Note that you should not call any page âindex.mdâ, since the existing include files then fail (I couldnât make it work and gave up for now) - just as a word of warning.
- We can in future come up with better templates and more advanced layouting. I have for now copied over most of it from the Eclipse SmartHome documentation infrastructure in order to be compatible with the md files that exist there.
- All you need to do in order to work on the documentation is to check out https://github.com/openhab/openhab-docs and locally run âjekyll serveâ. You can then access your local work at http://localhost:4000/. Once you are done with changes, simply create a PR against the openhab-docs repository.
- Please note that I will introduce some changes wrt the setup of Things/Items through the Paper UI (see here). So better donât spend too much effort on this part before the changes become available.
Regards,
Kai