Which branch in openhab-docs?

metin · April 17, 2018, 9:44am

I want to create a pull request to update the docs, but I’m not sure which branch to fork off

2.1-patch
2.2-patch
gh-pages
structure

??

Confectrician · April 17, 2018, 10:31am

gh-pages is the one to choose.
Please pay attention to the contribution guideline (especially the sign-off)

If there are additional questions, feel free to mention me here.

metin · April 23, 2018, 12:24pm

@Confectrician: Thanks for you reply. However, I seem unable to proceed with the docs. After I’ve made the amendments, I noticed there is a line saying “Attention authors: Do not edit directly. Please add your changes to the appropriate source repository”, but I’m not sure what this means. I haven’t seen any docs in the source projects. I edit the md files - is that correct or not? I seem not to be able to push the changes to a pull request, and I’m not sure if this is because my pull request is wrong because at the wrong place?

Confectrician · April 23, 2018, 12:29pm

Then you are trying to improve some docs that are generated automatically from time time.

Can you tell me what you are trying to improve?
Probably a special binding?

If i know what you want to improve i can point you to the right place/repository.

metin · April 23, 2018, 12:45pm

I’d like to update the HomeKit docs with more details about the configuration properties and their default values.
See https://github.com/openhab/openhab2-addons/pull/3332 for background info.

Confectrician · April 23, 2018, 12:53pm

You answered it nearly by yourself.
Binding Configuration is grabbed automatically from time to time from the corresponding Readme.md files.
Since homekit is a openhab 2 io binding, we can fin the correct readme file in the openhab2-addons repo.

Url:

github.com

openhab/openhab2-addons/blob/master/addons/io/org.openhab.io.homekit/README.md

# HomeKit Add-on

This is an add-on that exposes your openHAB system as a bridge over the HomeKit protocol.

Using this add-on, you will be able to control your openHAB system using Apple's Siri, or any of a number of HomeKit enabled iOS apps.
In order to do so, you will need to make some configuration changes.
HomeKit organizes your home into "accessories" that are made up of a number of "characteristics".
Some accessory types require a specific set of characteristics.

## Global Configuration

Your first step will be to create the homekit.cfg in your conf/services folder.
At the very least, you will need to define a pin number for the bridge.
This will be used in iOS when pairing. The pin code is in the form "###-##-###".
Requirements beyond this are not clear, and Apple enforces limitations on eligible pins within iOS.
At the very least, you cannot use repeating (111-11-111) or sequential (123-45-678) pin codes.
If your home network is secure, a good starting point is the pin code used in most sample applications: 031-45-154.

Other settings, such as using Fahrenheit temperatures, customizing the thermostat heat/cool/auto modes, and specifying the interface to advertise the Homekit bridge on are also illustrated in the following sample:

This file has been truncated. show original

So here’s the workflow to improve this:

Fork openhab2-adons master
Create a new branch
Improve the readme file
File a pull request to openhab2-addons repo
When your changes get merged, the docs will be updated for this, with the next run of our update script for bindings/external contents.

metin · April 23, 2018, 1:02pm

Thank you so much! I had searched for the docs there, but obviously not in the right location or just overlooked it! Though it makes sense to have the docs where the source is, of course!

Confectrician · April 23, 2018, 1:02pm

You’re welcome.