Documenting openHAB 2

Hi,

I am setting up a brand new install of OpenHab 2 with HABmin 2 and the ZWave bindings, in order to replace Indigo.
Doing so, I had to read dozen of pages of posts, articles and FAQ, and did not find a complete documentation.
So, I decided to create one while I am setting up everything.

It is a work in progress that is accessible there on Gitbook.

Feel free to comment the work done !

5 Likes

Documenting OH 2 is something that is in drastic need. I’ve been assigned getting things started with documenting OH 2 by Kai and unfortunately I am not doing the job in a timely manner (stupid life gets in the way).

See this thread.

Clearly you have an interest and ability. Would you consider taking over that effort to move it forward?

hey @rlkoshak,
iam also not the biggest expert in OH2. BUT I ve set it up sooo many times and I had the same issue, with collecting data left and right.
Maybe we can put heads together how to bring this topic to speed?
Maybe we can make this together. Iam not a jekyll expert. But already documented alot of projects.
I cant say I will do all…but I can take over some parts and document my steps also.
We need to somehow put the infos together and create sth. like OH2 in 5minutes…or OH2 for dummies.

…what are your thoughts? Dont give up :slight_smile:

hello,

I can take over this effort at least for the next months.

I used Gitbook in order to open to everybody the possibility to participate to the book.
My role will be on 2 aspects:

  • add content
  • read content proposed by other people and include it in the book (on this aspect, Gitbook in working the same way than Github).

Concerning Jekyll

I spent a few minutes on the Jekyll web site : Jekyll works with Markdown, which is good as Gitbook is also working with Markdown.
To my understanding, Jekyll is a solution to publish the documentation.

But Jekyll needs to be hosted somewhere.

Do we have Jekyll ready somewhere ?

Concerning the content

@rlkoshak : I read the conversation your linked to your answer. I am going to include your thoughts and create a table of content in order to set up the final goal.

I think I am more in the focus of a User’s manual, so far.

@MARZIMA : you can easily join Gitbook and propose additions to the document.

Concerning the platform

My experience is just on Macintosh.

Sincerely,

@bipphilippe and @MARZIMA

The the biggest hold up is getting the Jekyll builds as part of the maven builds for OH 2 and the OH Addons. Until we have that established there really is no place for the documentation to go to.

The intent is:

  • Documentation should go with the repo, so most of the documentation for the core of OH is actually already being hosted and created in the Eclipse SmartHome project. documentation for the core of OH 2 that is different (e.g. installation, differences caused by the use of karaf, additions) should go in the OH 2 core repo. Finally, the documentation for the addons should go with the addons repo. I think a user’s guide probably would go in the OH 2 core project.

  • The end goal is that the Jekyll markup would be “compiled” as part of the project build and ideally be submitted to the live website. Obviously a lot of details need to be worked out but that is @kai’s stated goal.

  • We want it to work just like the Eclipse SmartHome project so really this first step is taking what the ESH project has done and port it over to the OH 2 core and OH 2 addons repos.

The relevant repos are:

Eclipse SmartHome:

Use this as the template for what we need to do to get Jekyll setup

openHAB 2 Distro

This is the OH 2 Core repo where stuff like installation guide, user’s guide, etc would be documented.

openHAB 2

This is where much of the source code for OH 2 core that doesn’t come from ESH is hosted. The Jekyll framework should be added here but I’m not cure what documents would go here verses in the distro yet.

openHAB 2 Addons

This is where the specific addons documentation would go.

All three of these latter repos need a Jekyll project created and added to the maven builds.

This is the first step.

It really came down to me because I was the last person standing. But I really am struggling to find the time to make any progress on it and as @kai will tell you, we are in desperate need to get this set up so we can start to move forward on actually building the documents themselves. If either or both of you are able and willing to take this on and get it going it would be a great help to me and the rest of the OH community.

1 Like

Hi!

@bipphilippe & @MARZIMA, thanks for joining the efforts here!

@rlkoshak Since you are indeed behind the schedule (not blaming you!), I just did some tries for the Jekyll infrastructure yesterday and I think with a few more hours spent on it, I can get that going for the start. I’d hope that I have that ready early next week.

So if you all will then concentrate on the structure and the content, that would be gorgeous.

Shall we proceed like this?

1 Like

Ok for me.

Just let me know when the Jekyll infrastructure is ready (and how to access to it :slight_smile: )

1 Like

Sounds like a wonderful plan. I hate that I dropped the ball on this. Its so easy to find five minutes here and there to write forum postings from my phone (I’ve gotten better about the typos and weird autocorrect errors) but trying to code through a phone app is just not working.

1 Like

sounds good. If you have jekyll ready give us a sign and we might organize structure and content.
we should arrange how to step into this…is that ok @bipphilippe?
… @rlkoshak, dont worry mate. You can allways join if you got time.
…documentation, the job is not the most sexy thing :slight_smile:

It is easier to contribute to writing than the code right now. I can write on my phone during boring meetings and other down time periods. Coding not so much which has held me up on setting up Jekyll.

— sent from my phone :wink:

I have added @rlkoshak ideas in the book I have started.

As proposed by @rlkoshak, I propose to create two set of books :

  • a main book for OpenHab itself
  • a set of books for the extension (one per binding for example)

So my current work can be split in two books.

The first one is centered on OpenHab 2 and would have this Table of Content:
1 OpenHab basics

  • 1.1 What is OpenHab ? (to be done)
  • 1.2 Things, items and Co (done)
  • 1.3 Sitemap (currently working on it)
  • 1.4 Rules and Scripting (currently working on it)
  • 1.5 Bindings and other extensions (to be done)
    2 Installing OpenHab
  • 2.1 Checking Java (done)
  • 2.2 Installing OpenHab (done)
  • 2.3 Installing the designer (currently working on it)
    3 Working with OpenHab
  • 3.1 The different UIs (to be done)
  • 3.2 Installing binding and other extensions (to be done)
  • 3.3 Adding and configuring Things and Items (to be done)
  • 3.4 Working with Sitemaps (to be done)
  • 3.5 Working with Persistence (to be done)
  • 3.6 Working with rules and scripts (to be done)
  • 3.7 Looking to the logs (to be done)
    4 Advanced OpenHab
  • 4.1 Advanced Rules and Scripts (to be done)
  • …
    5 Tricks and troubleshooting (to be done)

The second one covers the Z-Wave binding and HABmin:
1 Setup

  • 1.1 Installing the extensions (done)
  • 1.2 Connecting to the Z-Wave controller (done)
    2 Adding devices
  • 2.1 Adding a new Thing (done)
  • 2.3 Configuring a Thing (done)
  • 2.4 The Wave Database (to be done)
    3 Other tools of Habmin
  • … (to be done)

The (done), (to be done) and (currently working on it) reflect today’s status.

I have updated the Table of Content of my current work to reflect that at :https://bipphilippe.gitbooks.io/openhab2-compendium/

Sincerely,

3 Likes

Just as a heads up that I am working on it: I have created a new repo https://github.com/openhab/openhab-docs, which uses eclipse/smarthome and openhab/openhab2-addons as git submodules, so that their content is directly accessible.
Github Pages automatically runs Jekyll on it and the result is automatically available on http://docs.openhab.org/.
I am still struggling with a few things, though. The menu does not expand yet and the symlinks do not seem to be working (despite the fact that they are working perfectl locally…).
I will continue on it tomorrow night, I only wanted to share some first results!

3 Likes

Great, @Kai.

On my side,

  • I have reorganized the documentation files in Gitbook in order to ease the more from Gitbook to the new repo when it will be ready.
  • I have read some documentation about Jekyll and Github pages in order to understand how they work.
  • I have read the documentation that is already in the new repo in order to see where it fits in the table of content.

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 :frowning: ).

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

Some more progress: I am now automatically generating the menu, so that it contains all 2.x bindings. We can do the same for other addons - I think this is pretty cool, because it means that as soon as a new binding PR is merged, it will automatically appear in the documentation without any manual action.

Do you all think that it is ok to have a dedicated repo for the documentation? The alternative is to create the gh-pages branch in the openhab-distro repo, but I am a bit worried that this means that the check out of the distro also requires the check out of the submodules, which would unnecessarily blow up the distro check out.

This is fantastic stuff! @Kai, I noticed that http://docs.openhab.org/features/bindings.html is only showing a subset of available bindings, but if you click on one, the menu that appears on the left does have all of them.

Yes, this is still the content of the manually maintained page from https://github.com/openhab/openhab-distro/blob/master/docs/sources/addons.md.

This should also be restructured to auto-compile the full list. I didn’t do this yet, because we will also need to extract the binding description and maybe we should directly go for some more structured meta-data like an icon/logo/image, a category etc.

As discussed above, I cared for the technical infrastructure and hope for others to help on the content now :slight_smile:

1 Like

Hi,

I will work on the content and hopefully I will have a first result Tuesday night.

1 Like

Ahh, that makes sense.

Wonderful progress! I like having the documentation in a separate repo. It lets the documentation team check out the and contribute without necessarily requiring a checkout of everything. However, I will paraphrase a comment made by @watou awhile back: “when making changes to the [documentation] one should check the changes against what the actual source code does.” I think this “rule” is more applicable to the reference documentation but we shouldn’t lose site of it in the tutorial/getting started.

Question: I probably have enough material between my postings, wiki examples, other people’s postings, etc to fill a book unto itself with examples and generic advice for the Rules DSL. Much of it seems appropriate for the tutorial but a lot of it seems a little advanced/complex for beginners (e.g. lambdas). Would this go into the reference documentation, go into the tutorial, or warrant a third section?