[Improvement] Documentation Rewrite

[CrazyIvan359]

So I started rewriting the docs... I will convert them to Sphinx at the same time (#42)

I have created a pull request for this and will push changes to that branch as I go. This way everyone will be able to see the changes and make corrections and improvements. Feel free to make pull requests on my branch if you have any contributions!

Readability

One of my main goals is make using this library more accessible. The current documentation is somewhat brief and technical, which is fine for me, but I know many openHAB users are not programmers beyond writing rules.

Structure

My other goal is to break up some of the larger pages (looking at you Jython Modules) and restructure the docs somewhat to make them follow a narrative (Home -> Install -> Getting Started -> Advanced). Since I will be migrating the docs to Sphinx, large pages like Jython Modules may stay a single page, but with the sidebar and chapters, will become much easier to navigate.

Examples

I also want to add examples with full explanations of how to convert existing DSL rules into rules for this library. There are already docs on how to write a rule and the 'But How Do I...' page (which I referenced often when I started converting my rules), but again they are concise. There are also concepts such as functions which differ greatly from the DSL to JSR223 which there doesn't seem to be much explanation of how to do. If one has written anything in Python before, they are fairly obvious, but for anyone just starting out I think some openHAB specific examples and explanation are needed.

Feel free to chime in with any suggestions you may have, be it on structure, examples you'd like to see, or places you think the docs need clarification

Mike

[5iver]

Awesome! I'd like to see docs inside the modules, which is pulled out for reading by Sphinx, similar to how the JavaDoc is done in the OH repos. I'd also like to see examples for each of the DPs, including templates. Keep in mind that the setup will be dramatically simplified once the addon is ready, so you should just change the setup to something like "Manual Setup". Another factor to be aware of is that the organization will be renamed to openHAB Scripters, and repos will be created for the other scripting languages. Whatever is done for the docs, will hopefully be transferrable to the other repos (formatting, structure, possibly content, etc.).

I'm excited to see what you come up with!

[CrazyIvan359]

So I have Sphinx setup and pulling docstrings from files, they will need rewriting in reStructuredText so they look nice. Before I get into that though I wanted to clarify how we want to serve this web content. Are you thinking about signing up for readthedocs.io and hosting it there, or would we just have the content in the repo and serve it from there?

If you want to see I can push what I have now along with the Sphinx build output

[5iver]

It would be nice to see. Just throw up a PR. My preference would be to serve it up from the repo or GH pages.

[CrazyIvan359]

PR is up, start page is Docs/_build/index.html
So far its only pulling from core.date.py because I know there is plenty of docstring documentation in that module. We still have to make base pages (see Docs/Core.rst and Docs/Core/Date.rst) but they are very minimal. These files also don't need to be in the Docs folder, they can be in the same folder as the module and just be referenced to in the .. toctree:: block in the appropriate page of the docs

[CrazyIvan359]

Pages looks like a good option. I have moved the source for the docs to /Sphinx and we can just build to /docs and have Pages serve that folder.

I will compile a guide to writing the files and docstring formatting needed for including new modules in the docs pages as I go and include them somewhere, maybe in a contributing section

[besynnerlig]

The task of rewriting the documentation for ideAlarm and weatherStationUploader was assigned to me.

For doing that, I've made a new branch.

I've relocated the community scripts README.md files as can be seen here.

I understand that there will be several viewpoints (is that correct english?) on this (For example Where to put the documentation files for a community supplied script) but this might serve as a starting point so that I can go ahead with writing the actual documentation.

To avoid that all my coming work must be discarded or rewritten I'd like to know how to proceed. Even though the topic is somewhat related, I should probably not spam this issue thread further. My question is if I should start a new issue or would it even be better to start a PR to allow further discussion?

[CrazyIvan359]

I think that knowing how to proceed will depend on @openhab-5iver and whether it makes more sense to rebase my branch to the current version of the repo given how much has changed.

If we go ahead with that then it will be easiest if you want until I have done that rebase. You will then be able to make a PR against my documentation branch with your changes.
If we do not rebase my branch, I am not sure what the best way will be.

Either way, any work you have done or will do will not need to be discarded. I suggest you download my documentation branch from my fork and look at the current documentation. You can view the HTML content by opening /docs/index.html. In particular, read the page on contributing as it covers how to add documentation to modules.

Let me know if you have any questions.

[Rick-Jongbloed]

Would it be a good idea to add a readme.md file with some basis documentation to each of the community scripts? For example, clicking on https://github.com/openhab-scripters/openhab-helper-libraries/tree/master/Community/IdeAlarm will show the scripts and the documentation for the script. I think it does even make sense to require a documentation (readme.md) file for each of the community scripts?
Never mind, i see @besynnerlig has already posted about this a few days ago.

[CrazyIvan359]

@ricadelic well, no. The content of the documentation is largely going to be IN the code files, so having a file with documentation in the same folder would be redundant. This rewrite/conversion to Sphinx I'm working on is not done though, so for the time being everything is still in the MD files.

[besynnerlig]

@openhab-5iver and @CrazyIvan359

I will probably be ready to submit a PR tomorrow (containing the documentation for ideAlarm and weatherStationUploader). Should I submit it against this REPO or to @CrazyIvan359 's personal REPO as suggested?

I don't expect it to be "mergable" initially but then at least we have a PR where we can review it, discuss it and suggest changes. Also, since the documentation will be totally reworked maybe we shouldn't use all our efforts to make it perfect at this time.

[CrazyIvan359]

@besynnerlig have you written your documentation according to what's in the contributing page in this branch? If so, make your PR here. If it's in MD files, maybe it would be easier to merge to master then convert to this format when I have more time to work on this.

@openhab-5iver any thoughts on my question from #131 yet?

[5iver]

@besynnerlig, please open a separate issue for further discussion about the documentation changes you plan to make. Put everything you can into the files themselves... Sphinx will read this and put it into the documentation for you. If you need more room for documentation, it would be easiest for everyone if you could please wait for the doc rewrite to get merged before submitting a PR.

@CrazyIvan359, lets get this done 😄! I think a separate repo for the documentation may work best. But to simplify things, let's worry about that for a potential phase 2. I have a lot of documentation updates to push, but will wait until Sphinx is in place. I'll need to take another look, but I don't think a rebase will be that difficult. I find Eclipse a little easier to use than VS Code, as there's a graphical rebase tool, but I also use about 3 other git apps too... none seem to have all the features I'd like. It should make it easier if you first change to the new directory structure in your branch before rebasing. You should backup your local repo first, in case things go sideways.

If you prefer, I have time today to do this, just make sure you've pushed your latest changes.

[CrazyIvan359]

@openhab-5iver if you have time today, go for it. I have nothing that isn't pushed. Sorry this kinda went dead, we had some repairs to do to the house that took over my life at the end of May. I should have some time to work on it more soon though. But please go ahead with the rebase if you have time.

I don't think this is merge ready yet though. There are still several pages from the original docs I haven't brought over yet. The core is barely half documented. And my gitignore has way more stuff in it than we will need at this point.

Also there will need to be some changes made to some of the root pages now that we are multilingual and the file structure has changed. (one of the more prominent reason I wanted to rebase this branch)

I will likely have time to work on it tonight, but I don't have any experience rebasing such major changes.

[5iver]

I'm wrapping up some changes to core.triggers to fix #141 and some other problems I saw. I'll start working on this in a couple hours. It'll help me to learn a bit more about Sphinx.

[CrazyIvan359]

@openhab-5iver I am ready to work on this now. Perhaps a more instantaneous method of communication would help? I could help with your learning of how Sphinx works, unless you are past that already.

[5iver]

I just got the PR done... as usual, it got a bit deeper as the layers peeled back. I need to break for dinner and will work on this after, unless you want to give it a shot.

[CrazyIvan359]

I know what that's like lol happens to me all the time. I'm just working on a debian vm so I can code on my desktop right now. Never done a big rebase so if you are wanting to get into it after you eat I'll wait. Email when you get back with whatever chat platform you want to use (facebook comes to mind simply for ease) and I help with the process and get you up to speed on Sphinx setup and use.

I will look over your code in the PR you did while you eat, and if I have time I'll work on an openhab dev instance so I can test it.

[CrazyIvan359]

Closed by #145