Closed 5iver closed 5 years ago
oh
or something identifying to the repo name.
one who grabs the folder to a non openHAB relatad download location might wonder what heper libraries are in there.On GitHub one can identify it with the organisation name, but not locally.
If there also should be docs included in the examples i would move that to the docs folder as a subdirectory. If we are going to fetch this at some time from the docs, it could be easily integrated and nothing has to be chagned for that at a later point.
- Basically i would agree bout maybe add also an oh or something identifying to the repo name.
Good point. My wife had pointed this out too, but I was 50/50 on whether to include it or not. Let's go ahead and give it the full name... openhab-helper-libraries. It reminds me though that we might want to work in a way to communicate that this is not an official OH repo.
- Is script examples meant to be for real js/py/whatever files or also for explanations about them?
They are mainly working scripts as examples, but I think they would be good to have documentation in them, like your forum post. They haven't evolved much, so work them as you see fit! The Jython docs are being reworked, and all scripts and modules will contain their own documentation that will be pulled into a GH site. Maybe something similar can be done for Javascript.
I'd prefer to see as much consistency as possible between the languages, but that's not always going to be possible. For non-language specific info, we will have at least the README at the root of Docs.
I think the example scripts should evolve into Design Patterns. Having both seems redundant and I think the new docs format will make them easier to understand having code and explanations in one place, as @confectrician says.
There is an extension for Sphinx that can pull most JSDocs from the files. It's use is a little more involved than with Python code files, but not so much that it's not worth the trouble. I could work on getting that going once everything is merged.
I was thinking that Community
and community
(and Core
vs core
) are similar folder names and might confuse beginners. From a pedagogical point of view it may be easier if the were more distinguished from each other. Not a big issue for me though, just a thought.
I think the example scripts should evolve into Design Patterns.
That's coming. The lucid migration has a Design Patterns directory and a TimeOfDay example. I'd like to see examples for all of them, with templates!
I was thinking that Community and community (and Core vs core) are similar folder names and might confuse beginners.
Let me know if you can think of something better. I went around and around in my head with how to name the directories when originally restructuring the repo, but this was the best I could come up with.
I was thinking that Community and community (and Core vs core) are similar folder names and might confuse beginners.
Let me know if you can think of something better. I went around and around in my head with how to name the directories when originally restructuring the repo, but this was the best I could come up with.
What if we renamed the /Community
folder to /Community Packages
?
I think /Core
is the best name for that folder. Most users won't be doing anything with it beyond the install and installing Community packages, both of which may soon be obfuscated behind install scripts or even within openhab if things go well
What if we renamed the /Community folder to /Community Packages?
But there are scripts, transforms, etc. in there too, not just packages. Maybe Community Contributions? But it's all community contributions, so that's sort of confusing too.
Hmm, yes that does make it more complicated. We could go the same way as OH and use /Community Addons
but that could lead to users thinking that these are OH add-ons not our scripting add-ons...
I like openhab-helper-libraries
for the repo!
How about Community Stuff
or Community Solutions
? Scripters Solutions
or only Solutions
?
Don't know if its really better (Core vs core):
CORE
for better visibility? Too noisy?
I asked myself whether we were not already formulating the jsr223
more generally like scripts
. But currently it hits jsr223
the best.
What content will end up in the Docker directory?
How about Community Stuff or Community Solutions? Scripters Solutions or only Solutions?
Community Contributions?
I asked myself whether we were not already formulating the jsr223 more generally like scripts. But currently it hits jsr223 the best.
/automation/jsr223/ is hard coded in ScriptFileWatcher for where scripts are loaded from. But I plan to propose changing this to just /automation/ and exclude /automation/lib/. The Jython docs currently suggest putting the standalone Jython jar in /automation/jython/, but I think it might be better in /automation/lib/ or ${OPENHAB_RUNTIME}/lib/ext/, and then set environment variables for JYTHON_PATH and JYTHON_HOME (on my list of things to test).
What content will end up in the Docker directory?
This directory currently exists in the repo and has a Dockerfile for building a Jython Docker container. Doc is here.
All done! We didn't really come to a decision on what/if to rename Community, so I left it for now. If there are any strong opinions, shout it out and I'll change it. If you have them, you'll need to update your local repositories to point to the new location.
All done! We didn't really come to a decision on what/if to rename Community, so I left it for now. If there are any strong opinions, shout it out and I'll change it. If you have them, you'll need to update your local repositories to point to the new location.
Great! I'll find some time in the very near future to test things out.
Great! I'm setting up symlinks right now (probably should add this to the docs too). Let's hold off communicating the change until everything is tested and the JS libraries have been added. I'm adding a note to the readme that things are under construction.
Nice progress today. 👍 Thanks for the work.
There is no Core/automation/jsr223/python/community/personal
folder in the repo. Is that intentional?
I noticed that... no, not intentional. I must have forgotten the readme (empty folders disappear). I'll add it. TY!
I noticed that... no, not intentional. I must have forgotten the readme (empty folders disappear). I'll add it. TY!
Thanks.
There is a difference in where different Community scripts are stored. E.g. Community\IdeAlarm\automation\jsr223\python\community\idealarm\idealarm.py
vs Community\WeatherStationUploader\automation\jsr223\python\community\weatherStationUploader.py
Should we store the scripts in their own community/subfolder
or not?
Now I'm getting concerned. I remember finding this and adding the directory for weatherstationuploader. I was sure I had created the readmes in the personal folders too. I'll go check through everything again. Gremlins!
OK... this was silly. The personal directories were stripped because I had added them to gitignore. The WeatherStationUploader change wasn't made because I created the directory and forgot to copy the files into it (hard to see that in VS Code). Fixed in #122 and #123.
OK... this was silly. The personal directories were stripped because I had added them to gitignore. The WeatherStationUploader change wasn't made because I created the directory and forgot to copy the files into it (hard to see that in VS Code). Fixed in #122 and #123.
Thanks a lot!
In order to make it easier for people to find and use helper libraries, I plan to rename the org to openHAB Scripters and add libraries for languages other than Python. I had originally thought creating repos for each language would be best, but I'm now pretty solidly leaning towards putting everything in the same repo. This would mean a new directory structure, but one download would get you all libraries, scripts, examples, etc. for all languages. A single repo is also likely how it would be structured if/when the helper libraries are ever moved into the OH organization.
These changes will happen soon after the lucid migration and other PRs are merged. The lucid changes will need at least one more commit, but it is currently being tested and should be merged this week. I already have @lewie on board for migrating his JS libraries and to come on as a mintainer, with support from @confectrician. Hopefully someone will step forward for the Groovy libraries. The plan will be to create similar functionality for each of the languages.
For the name of the organization, I propose 'openHAB Scripters'. For the repo, I propose 'helper-libraries'. WDYT? Any input would be appreciated!
Proposed directory structure: