Documentation for ideAlarm and weatherStationUploader are outdated

[besynnerlig]

Describe the bug
The documantaion for the community contributed packages ideAlarm and weatherStationUploader are wrong. They are written for an older version and are not accurate.

To Reproduce
N/A

Expected behavior
N/A

Environment (please complete the following information):

• openhab-helper-libraries

Additional context
The old documentation for ideAlarm consists of a 12 page Wiki that can't easily be migrated to the python source file.

[5iver]

Could it be migrated to the wiki in this repo? Although, the documentation rewrite should be merged today.

[besynnerlig]

Could it be migrated to the wiki in this repo? Although, the documentation rewrite should be merged today.

I guess it could but I'm almost finished the md files including updating the text.

[besynnerlig]

I've pushed the new documentation to my private fork.

Documentation for ideAlarm and weatherStationUploader.

This is at least a starting point. It's not perfect and the english is at a level where it's most likely understandable but obviously not written by someone who has english as the first language. Let's hope that native english speakers will contribute with fixing that.

Furthermore there are a few references to generic documentation that yet doesn't exist. For example there's no generic instruction yet for how to install a (any arbitrary) script/package contributed by the community.

Honestly I don't know how the ongoing rebase and documentation rewrite is going to affect the documentaion for ideAlarm and weatherStationUploader. I haven't had the time yet to study it. I have been instructed to wait to submit a pull request until the new documentation thing is done. However both ideAlarm and weatherStationUploader are in urgent need of a working documentation so I hope it won't take to long. Please give me a hint when it's a good time to submit my PR. Thanks.

[5iver]

The structure is all there for #90 to be merged, but the documentation itself was a little outdated and did not have JS and Groovy. So, we decided to get that cleaned up before merging, since the work had to be done anyhow and it'll be nice to have everything in place before going live. If you haven't taken a look at it yet, I think you'll be quite pleased with the change! I don't see it taking more than a day or two to finish up.

The markdown files you have made will need to be converted to reStructuredText (rst) for use in Sphinx. There is some more information in #90. That is exactly what Michael and I are doing right now in the final leg of the doc rewrite. It would be great if you can migrate them on your own, but if not, we can get to them after.

[besynnerlig]

The markdown files you have made will need to be converted to reStructuredText (rst) for use in Sphinx. There is some more information in #90. That is exactly what Michael and I are doing right now in the final leg of the doc rewrite. It would be great if you can migrate them on your own, but if not, we can get to them after.

Thanks!

I could learn about Sphinx but I'd love if someone would offer to help with migrating the documentation for ideAlarm and weatherStationUploader.

[5iver]

Everything is done except for the second half of But How Do I, then we can work on your docs. Should be done by tomorrow.

[5iver]

@besynnerlig, we finally got it all done, and it was worth it! Hopefully you've taken a look at the new docs. I just spent all night getting your documents migrated to reST and using proper formatting (one sentence per line). I'll do another review later today and also build out the community instructions. Should be able to merge these tonight.

[besynnerlig]

@besynnerlig, we finally got it all done, and it was worth it! Hopefully you've taken a look at the new docs. I just spent all night getting your documents migrated to reST and using proper formatting (one sentence per line). I'll do another review later today and also build out the community instructions. Should be able to merge these tonight.

Wow, it looks great @openhab-5iver . What a difference!!!

Thank you for all the time and hard work that you've put into this.

I have one question though, as you know I've recently reworked the documentation for ideAlarm and weatherStationUploader. After that I've pushed the new documentation to my private fork.

Maybe I don't have the proper link to the new documentation but the new documentation for ideAlarm and weatherStationUploader is outdated. It doesn't seem to originate from the latest version (ideAlarm and weatherStationUploader) that I've prepared.

[5iver]

I'm about to push the changes 😉.

[5iver]

OK... try that! 😄

[5iver]

The table of contents gets buried a bit by the docstrings, but it's visible in the sidebar. We could just show the main docstring for idealarm/init.py. Let me know if that would be your preference.

[besynnerlig]

Lovely!

The table of contents gets buried a bit by the docstrings, but it's visible in the sidebar. We could just show the main docstring for idealarm/init.py. Let me know if that would be your preference.

I think it works fine as it is now even though it's a bit unexpected to find a TOC last on the page. I haven't developed a preference of my own yet so I trust that you know what works best in general.

There are references in the documentation for Install or update a Community package, a part that hasn't been written yet.

Should I add that as a separate issue or is it something that's already going on?

[5iver]

There are references in the documentation for Install or update a Community package, a part that hasn't been written yet.

Should I add that as a separate issue or is it something that's already going on?

I added this along with your docs... https://openhab-scripters.github.io/openhab-helper-libraries/Getting%20Started/Installation.html#community. There's not much to it, but there's not much to it! Please update it if you think it needs more. We also need to get some documentation together for using symlinks and git... #164. I'll get to this eventually, but I've had enough of documentation for while!