Docs Improvements

[rkoshak]

I want to discuss improvements to the docs before I start to make changes in a PR.

I've converted a number of my rules over to using the library, at least those that I could do without the factories stuff that isn't working (see #15).

My current ideas include (in no particular order):

1. Add instructions to enable logging in log4j2.xml (or change the logger namespace to use one that will be logged by default)

2. Add a "But How Do I" page or section that shows examples for how to do common stuff similar to what the JSR223 Helper Library does. This becomes even more useful than a straight reference document which we need too and I think is already pretty good for a start. the Rule Builder API section is a good start for using that. We need sections for stuff like "access the Item that triggered the rule", "get the previous state of the Item", "filter, map, reduce the members of a Group", "call a Thing's Action" and stuff like that. Some of that is already there scattered throughout the API docs but it's easier for users when it's a little more consolidated.

3. TBD Once it's written, link to the Getting Started Tutorial where a more detailed step-by-step set of instructions and descriptions.

4. The descriptions of a lot of the classes and methods are a bit anemic. For example...

ohItem.isUninitialized ⇒
Whether this item is initialized.

Returns: true iff the item has not been initialized

If I'm new to OH I don't even know what that means. And if we were to be technical it's misnamed because NULL is the only state that indicates an Item is uninitialized. UNDEF indicates the Item's state is unknowable. But I'm not going to argue to change the name of the field but I would change the description to something like "Whether this item**'s state** is NULL or UNDEF.

I don't think we are doing any favors by being too vague like that. Even I had to look at the source to verify that's in fact what it does.

5. If possible, link to the code from the API docs. So, for example, if I clicked on the "ohItem.isUninitialized =>" above, it would take me to the actual function that implements it. That way even if the description isn't clear enough the user can easily look at the actual source code to clear up confusion. I'm not sure deep linking to code is possible in GitHub though.

6. The Log section needs to be expanded further because, at least right now, the structure and formatting of the logs are significantly different from what we are used to.

7. If possible I'd reorder the structure of the API section to put the most commonly used stuff at the top. I would put the Objects before the Classes and order them by items, log, actions, rules, triggers. The order of the Classes are fine.

8. It would be really great if we could split these into multiple pages. But I don't know how well the openhab-docs builder handles that. I know it didn't seem to do so well with the MQTT binding.

There are various typos and such that need to be corrected and I'll try to make a go at that in a separate PR. However, I think some of them are in code, not just the docs which might cause some problems. For example "ohItem.upsertMetadataValue(namespace, value) ⇒ Boolean"

[digitaldan]

So i was thinking about opening a PR to add

<Logger level="TRACE" name="org.openhab.automation.script"/>

to the openhab distribution log4j2.xml file seen here:
https://github.com/openhab/openhab-distro/blob/dd6712ad66234fb687849971a5feaf3e7f0b69e7/distributions/openhab/src/main/resources/userdata/etc/log4j2.xml

But now i'm thinking, should user script logs be going to their own file? Like events do? I don't have a strong preference either way. Any thoughts on what would be easier for users? I personally tail the openhab log almost exclusively for stuff, so thats where i would tend to put it.

[jpg0]

One nice thing about using the main log is that sometimes scripts trigger errors in other components - for example accidentally passing a null into a framework class. If this happens, the error will be logged in the main log, so the danger of another log file is that script writers may end up needing to use both anyway.

[digitaldan]

Thats a good point, i think i'll stick with the main openhab log.

[digitaldan]

openhab/openhab-distro#1340

[digitaldan]

FYI, i have the actual API docs now being generated anytime we push to master. These still need to be cleaned up, but it's a start.

https://openhab.github.io/openhab-js/openhab/0.0.1-beta.1/index.html

err now its at https://openhab.github.io/openhab-js/openhab/0.0.1-beta.2/index.html , will need a way to preserve previous versions....

[Confectrician]

Do you want to include the docs into general openhab docs at some point?

I am currently working on a GitHub action based solution for openHABian docs, to get them fetched indipendent from our Jenkins ci.

Goal is to trigger a redeploy based on a release of an external repo like openHABian.
This way we want to ensure a up to date stable documentation for parts that have shorter release cycles then openHAB itself.

[digitaldan]

Thanks @Confectrician for the idea, i think at some point yes, we will want to push the README, or at least part of it minus the JavaScript API docs that get generated (they are very verbose), right now its a little bit of a mess (my fault) :-)

[digitaldan]

FYI openhab/openhab-distro#1340 was merged which is great.

[rkoshak]

Sorry I'm late to the party. In addition to the error log correlation, it has pretty much always been the case that rules log to openhab.log by default so it would be more expected that it would continue to do so. It would also have fewer impacts on those running openHABian which deploys Frontail to view the logs in the browser. There would need to be changes made to that config to pick up the rules logging. So there are other good reasons to keep it logging to openhab.log by default.

I'm still exploring the ins and outs of the library and want to get a bit more experience before I start to work on updates to the logs.

[digitaldan]

Well, our binding was accepted into 3.2 , so that means we need to get our documentation going asap!

[digitaldan]

Fyi latest docs are at https://openhab.github.io/openhab-js/openhab/1.2.0/index.html

I realize there is much to be desired with these, so its something i'll try working on , i would really like to autogenerate our docs from code as much as we can.

[digitaldan]

@rkoshak should we close this?

[rkoshak]

Yes, I think most of the above had already been done and the docs have changed so much success this was opened some isn't relevant any more. As we find stuff we can add new and smaller issues as we go.