[WIP] NGRE/JSR223 Documentation refactoring

[5iver (Scott Rushworth)]

I’ve also been holding off in communicating about NGRE and scripted automation. There are a few more things I’d like to wrap up, but getting close! In regards to naming, I prefer using Scripted Automation rather than JSR223, as it’s really javax.script and this works for when/if GraalVM is implemented. I will be submitting a PR to remove/rename the /automation/jsr223/ directory, but that would be for 3.0.

@rlkoshak

the big one that comes to mind being the broken System started triggers

I fixed this a few months back , but have yet to merge the Jython helper library portion, as it will be included with an upgrade to support the 2.5 and the ESH reintegration. However, the StartupTrigger will only be available with helper libraries, until an official one is written.

@rlkoshak

I believe the plan is to distribute the helper libraries so they can just be used, no extra download and update necessary

My plan is to implement a Scripting API (probably 3.0) and migrating/expanding the Core Actions, which will eliminate the need for most of the helper libraries. Distributing libraries is basically last on the list. However, with consolidation of the libraries, I also plan to extend the Groovy and JS libraries to match the functionality of Jython. JS libraries will benefit a lot from OH support of JDK9. There also appears to be a recent issue with Groovy, which will need to be corrected before its libraries can be done.

@rlkoshak

similarly, I believe the plan is to distribute the Jython jar file (I don’t know what Groovy needs) so all three languages are equal full class citizens in the OH ecosystem

WIP! Hopefully ready in time for 2.5. The Scripted Actions/Conditions for Jython and Groovy are already in the snapshots…

The raw API is ugly and NOT easy to use. I suggest directing beginners to the helper libraries, as the raw API will be a big turnoff. This will improve with the scripting API and Core Actions, but I think any tutorial should be kept to a minimum ATM, and suggest to use the helper libraries and their documentation. The common piece that might work in the official docs is the Action content, which is what you would need for scripted Actions/Conditions in a UI, so using the ‘events’ object, ScriptExtensions, thing actions, binding actions, and language specific tutorials like if/then/else, iterables, etc. If work is going to be done now, it needs to be weighed against the upcoming changes, which will quickly make them obsolete and IMO not worth the effort. I suggest focus on the helper library documentation, and pull some of the generic info out of them to put into the official docs.

I’ll be getting some posts out soon!