Openhab-addons: Adapt skeleton for readme.md

[davidgraeff]

As of openHAB 2 the rest interface and OSGi console commands are equal ways of configuring your openHAB next to the classic xtend based files. The java scripting and the new rule engine are also equal competitors to the xtend rule DSL.

I therefore suggest to no longer require people to have xtend examples in their binding readmes.

If contributors want to, they can instead provide a separate xtend_examples.md file.

(The website and docu team would need to index those files and provide them via a separate menu entry or example tab.)

The reasoning: I'm using openHAB for a year now and I have never touched any xtend files. I have no idea about the syntax and I don't want to and I don't need to, same with other new people to OH. (I had like a dozen fixes to the examples I made for mqtt.)

Cheers, David

[J-N-K]

David, you (and me) do not like the textual configuration (at least for things, and I really hate the rules). But: from my experience with OneWire and DMX I learned that there are quite a lot of people who prefer it and need good documentation for that.
IMO we could drop that for OH3 but should not do so for OH2. Better fix some documentation.

[davidgraeff]

My idea is not to remove those but to move them to a separate file. The advantage is that the website script then even have a semantic idea of the file content and can apply special rendering like an example tab.

Take the website of the JavaScript framework angular for example. They have special renderings applied for examples. You can for example have a copy to clipboard button below a code box etc.

[davidgraeff]

@openhab/2-x-add-ons-maintainers

[Hilbrand]

If we want to move things out of the readme. I would suggest to create sample configuration files instead of a md file. For example an example.things. I believe for the website already some preprocessing is done to use the readme md files. This can be extended to rendering these sample configuration files. The big advantage would be when we would change syntax we can automigrate all those examples. We also could add a checker that checks the syntax of those files so david doesn't create invalid examples :smile:
While we're at it. There was also the wish to generate the channel list from the xml files for the documentation. Maybe we can also look into that too.

[davidgraeff]

Do we do an own directory, maybe replicating the directory structure of oh itself?
The mqtt binding has like 8 examples and multiple things and items defined.

So there would be a "rules", a "things" and so on sub-directory within an "example" directory.

[gitMiguel]

How about creating new doc folder under src? Depending if src/doc is found or not, documentation would be parsed from multiple files or then the current way from single README.md file. Different tools could then be used to create content dynamically.

|- src/main
|- src/main/resources/ESH-INF
|- src/test
|- src/doc
|---- channels
|-------- channels.md
|---- things
|--------things.md
|---- rules
|-------- xtend
|------------ xtendRules.md
|-------- jython
|------------ jythonRules.md

[Confectrician]

We have also implemented a "tab" extension within the docs, which was introduced on the dies of bringing different configuration styles together.

See https://www.openhab.org/docs/configuration/jsr223.html for an tabbing example.

[gitMiguel]

Those tabs would work with different language rule examples. Maybe even things and their corresponding configuration could be under tabs?

Edit:

Looks like those tabs are written in single file and separated with special tags. Is multiple file structure with tabs somehow supported?

[Confectrician]

Those tabs can be used for everything you want.
See https://github.com/openhab/openhab-docs/blob/master/configuration/jsr223.md for an implementation example.

On github the tab markdown is rendered as text, since github doesnt support it.
The tab contents then get displayed vertically in the written order.

Multiple file structure:
I think this would need to get merged via script, when generating a docs/addons site.