More news soon
(I think that I have to type up a more detailed “HowTo contribute to the documentation” before I start contributing content to it myself :))
For starters you could look out for smaller tasks where an existing article needs to be edited. All of the qick fix issues linked above (but also many others!) would be such issues (@RHINESEL I’ve removed the Tutorials ticket from that list).
Solving these tasks is very easy! You do not need Jekyll nor any deeper git knowledge. You can simply select one issue, open the related GitHub document, add the needed changes right in the online editor and propose these changes as a “Pull Request”. This process allows others to review every change and suggest further improvements. One special detail: According to this you need to “Signed-off-by”-mark your commits - please do not forget that.
If you want to add a new article (e.g. Tutorial page) it would be the easiest to discuss this in the related issue first. We can help with the needed steps there.
Looking forward to some great contributions Best! Thomas
Here is a quick step-by-step I used to get going. I agree it is complicated but I do understand why these steps are necessary. These are taken from some notes I made and I really haven’t kept up. There may be errors or omissions. Note that this is really only necessary for major updates like the creation of a new document or major structural changes. For quick fixes use the online editor as @ThomDietrich described.
You must have a GitHub account.
Once logged in click on your icon in the upper right and select settings.
If you have ssh set up (on windows this would be putty tools installed and pagent running with an ssh key loaded) add your ssh public key under SSH and GPG Keys. If not, generate a “Personal Access Token”. You need one or the other set up to interact with Github from the command line. On Windows you could also get the Github Client program but I have not had good experiences with it.
Add the original repo as the upstream with the command: git remote add upstream git@github.com:openhab/openhab-docs.git NOTE: use the http address if you did not upload an ssh key
Checkout the gh-pages branch with the command: git checkout gh-pages
Merge the changes from the upstream with your fork with the command: git merge upstream/gh-pages
Create a new branch for the one issue you want to work on with the command: git checkout -b <name>
Push the branch to github using the command git push origin docker
Make your changes.
As you go, add and commit changes with the commands git add . and git commit -m "message"
When your changes are ready, go to the github page for your fork and create a PR. Make sure that the openhab/openhab-docs and appropriate branch is on the left and your new branch is selected on the right.
Make sure to reference the Issue in your comment. Closes issue #XXX
Additional commits can be made to the PR by making the changes locally to your branch and pushing the commits.
you can work on more than one issue at a time by working on each one in a separate branch.
Before creating a new branch, make sure to do steps 7 and 8 before creating a new branch to work on
When working with the docs, you can serve up the web pages as they will appear by changing directory to the source files and run jekyll serve and browse to http://localhost:4000/.
NOTE: The jekyll that came with Ubuntu as of a few months ago is not new enough and messes up the code blocks. Install the most recent version is possible.
I also found a small bug with the service wrapper.
The java classpath in the default file that is created by the wrapper:install command is wrong (points to %KARAF_BASE% while it should be pointing to %KARAF_HOME%)
FYI karaf base and home should be the same by most of the time. Karaf home variable is used only when one karaf installation serves multiple processes. Wrapper script points to boot/main class which will not be present in children instances.
Even if its not used in OH better dont change it.
// ok, after checking
Thank you @splatch for the reply. I need some help here because I am stuck (I am trying to create a doc section on windows service installation steps)
I think that the problem is that the Karaf service wrapper installation does not take this directory layout file into account.
For example, if I execute:
openhab> feature:install service-wrapper
openhab> wrapper:install --name "openHAB2" --display "openHAB2" --description "openHAB 2 Service"
Creating missing directory: C:\openHAB2\userdata\bin
Creating file: C:\openHAB2\userdata\bin\openHAB2-wrapper.exe
Creating file: C:\openHAB2\userdata\etc\openHAB2-wrapper.conf
Creating file: C:\openHAB2\userdata\bin\openHAB2-service.bat
Creating missing directory: C:\openHAB2\userdata\lib\wrapper
Creating file: C:\openHAB2\userdata\lib\wrapper\wrapper.dll
Creating file: C:\openHAB2\userdata\lib\wrapper\karaf-wrapper.jar
Creating file: C:\openHAB2\userdata\lib\wrapper\karaf-wrapper-main.jar
Setup complete. You may wish to tweak the JVM properties in the wrapper configuration file:
C:\openHAB2\userdata\etc\openHAB2-wrapper.conf
before installing and starting the service.
MS Windows system detected:
To install the service, run:
C:> C:\openHAB2\userdata\bin\openHAB2-service.bat install
Once installed, to start the service run:
C:> net start "openHAB2"
Once running, to stop the service run:
C:> net stop "openHAB2"
Once stopped, to remove the installed the service run:
C:> C:\openHAB2\userdata\bin\openHAB2-service.bat remove
openhab>
The C:\openHAB2\userdata\etc\openHAB2-wrapper.conf has the following lines:
Hey @Dim,
I did check and you are completely right - wrapper.conf is completely invalid because it is made for vanila karaf. So far there is no easy way to customize that. It is possible to override this resource with a fragment “extension” which will be specific to OH2 so generated resources will be in syns with what OH needs.
Because service wrapper replaces startup scripts all environment variables which are set in oh2_dir_layout should be clonned to it, meaning
It might work without it in first moment but later on every code which will call getenv("OPENHAB_USERDATA") will behave differently depending on the way OH was started (command line or service).
because with only the oh2_dir_layout variables included in the wrapper.conf, I was still getting some errors.
With these 2 changes, I got the windows service working… but…still… I am not sure if the system is stable now… I may have missed some parameter or other environment variable in the wrapper.conf that will show it’s ugly face later down the road…
As @ThomDietrichsuggested: The right move here is to create a script (which will be distributed with OH2) that produces a proper wrapper.conf file (and maybe takes care of the service installation commands also) so that people will not have to customize it to make it work. We need some scripting support to make this happen… @xsnrg made a very nice script for linux (for upgrading a manual OH2 installation) but we need 2 scripts for windows also (one for manual upgrades and one for generating a proper wrapper.conf/installing the windows service automatically)
I made my first contribution to the documentation several days ago and I think I’d like to try and fill in some more. The two I’m most interested in tackling right now (Things and Services configuration) are completely lacking text, but I have some questions before I attempt to take these on.
First, a couple of general questions:
Is anyone already working on this? I don’t see any PRs or issues logged for the Things and Services pages, but I might have missed them.
Should I log an issue for each of the missing docs before I attempt to write them?
For the things configuration page, I’m thinking about covering:
Discovery based configuration
File based configuration
Basic syntax
A few key examples
Highlighting the fact that some bindings (for example, Z-Wave) do not currently work properly with things files
Does this look like a good start? Anything I should add / remove?
For the Services configuration page, I question what should really go here. I would like to add some documentation explaining the config files that go in the /conf/services folder, but I’m not sure if this is the appropriate section or if that has been adequately covered elsewhere. I’m guessing this is the place since I haven’t been able to find consistent info on it.
The Things article is an important one to be written. There is currently no Issue for it and Yes, that’s exactly where you should start!
Over there we can also discuss all details and topics that you want to talk about. Your bullet points already contain a good summary. Maybe you can have a look at the items and the sitemap articles to get a feeling for the style we went with till now.
The last part about which bindings actually do and do not support Things should go into the introduction I’d say.
Regarding Services: I was also not sure about this one yet It was supposed to describe the services files. However these are becoming more and more irrelevant with the rise of Paper UI and there is also not much one can say other than “Set the options according to your needs” Let’s start with Things now and Services can wait a few more days.