search

openhab-scripters / openhab-helper-libraries

Scripts and modules for use with openHAB
Eclipse Public License 1.0
88 stars 70 forks source link

Documentation for ideAlarm and weatherStationUploader are outdated #144

Closed besynnerlig closed 5 years ago

besynnerlig commented 5 years ago

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):

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 commented 5 years ago

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

besynnerlig commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

I'm about to push the changes :wink:.

5iver commented 5 years ago

OK... try that! :smile:

5iver commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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!