[Improvement] Documentation Rewrite

[CrazyIvan359]

This pull request will be used as a working branch for the rewrite of the documentation, including the migration to Sphinx. Feel free to discuss here or in the issue (#89) if you have any suggestions. If you have any contributions you would like to make while this is not part of the main codebase, pull requests can be made to my branch

[CrazyIvan359]

@openhab-5iver Check out this commit. I restructured the file structure so that the docs source is now in /Sphinx and the build output is in /docs to make GH Pages happy. I have also switched to the RTD theme, which allows us to have the navigation sidebar.

I have also got doc-source in the module working. The Modules toc will look for any .rst file in lib/python directory, so each module needs to have a main docs page with the same name (to avoid naming conflicts only). If it is a larger module, additional pages can be created inside the module and referenced from main page (like this new commit does with the core module). If the module is simpler and a single page will be enough, then all of the content can be written on a single page.

[5iver]

I would really like to dig into this, but I probably won't get a chance until late this weekend... need to prepare for holiday guests, and I'm already having a hard time tearing myself away from figuring out how to make a Jython addon... :smile:

[CrazyIvan359]

No worries, I have Easter stuff happening as well. I will probably have time tomorrow to work on this, but I think I have a good setup now so it will be more content. Whenever you have a chance to look is good, I certainly won't be done this weekend. Sphinx settings are in /Sphinx/conf.py and if you want to rebuild the pages you'll need to pip3 install sphinx mock and run sphinx-build Sphinx/ docs/ from the repo root.

To anyone wanting to preview the docs: you will have to clone or download my branch in order to view the html content. GitHub does not allow viewing rendered html files.

[mjcumming]

I would really like to dig into this, but I probably won't get a chance until late this weekend... need to prepare for holiday guests, and I'm already having a hard time tearing myself away from figuring out how to make a Jython addon... 😄

Scott, are you working on a way to do a jython "binding"?

[5iver]

Yes... it's morphing into an extension service for rule templates, but I think I can isolate that functionality for a v2. I'm having a bit of trouble getting Jython to work from an addon, so may need to scrap it and go another direction.

[5iver]

@CrazyIvan359, sorry for this, but the lucid migration has bumped this in queue. It shouldn't take much to get it wrapped up. I haven't forgotten and really look forward to see what you've done here!

[CrazyIvan359]

@openhab-5iver don't worry about it. I haven't had much time to work on it this week and weekend, snow finally finished melting and we've had several garden projects just waiting for that. Lots more work to do before its ready to merge anyway.

In regards to the Lucid migration, that will make some pretty big changes to the repo I'm guessing. I was thinking it might make for a cleaner commit history if I took my finished work in this branch and added it all in one shot to a clean branch of the master at that time. Does that make sense, or is it better to keep the commit history?

[5iver]

The lucid migration will only be additions... shouldn't be any changes to anything existing. So, this PR should be fine. Don't worry about too many commits, as I can squash + merge when it's ready.

Snow... yuck! Just split some rhizomes and got another row of hops in the ground. The other row is already climbing and gotta cut the grass tomorrow!

[CrazyIvan359]

Squash-merge, I'll have to read up on that. I see you've added a .gitignore now, I'll clean mine up when this is ready to merge so that only things we need are there, I'm just using a generic from github right now. I haven't looked at the lucid branch so I don't know what it's adding, I suppose docs can be added to it after the bulk of this is finished.

Yes snow, too much fell this winter (and spring, it snowed a week ago!). We have a couple indoor greenhouses full of plants getting too tall for them that we can't plant out yet.

[5iver]

Scott, are you working on a way to do a jython "binding"?

@mjcumming, I just reread this and realized that I misunderstood your question. I am not working on a Jython binding, but an addon that installs/configures Jython. However, it is very possible to make something in Jython that is like a binding. Most of what is needed is already found in the modules and component scripts. It also may be possible to make a true binding, which I will be looking into.

@CrazyIvan359, I cloned your repo and really like it! So much better than markdown! My only concern right now is where to put it, as it seems to clutter up the repo and I don't think anyone will want to download the Sphinx stuff. Could Sphinx read files in from a separate repo? It looks like Javascript could be used with Sphinx, but I'm guessing that it will probably be done differently. So, I'm thinking a jython-docs repo. Another option is to put this into a gh-pages branch that the GH page points to, but I haven't thought of a way to incorporate the other languages doing it this way. Although, if there was a quick/easy way to add in the docs from Javascript and Groovy files, this sounds best. @Confectrician, do you have any thoughts about what to do for Javascript documentation? Markdown for everything, or pull in some of the docs from the files?

Is there a setting for the screen width? This is what it looks like for me (Firefox), and there is a lot of empty space...

[mjcumming]

@openhab-5iver Scott, was thinking of a python based binding. Agree, we can essentially do that already. Is there the potential to have it configurable via the standard OH interface?

[mjcumming]

@CrazyIvan359 I could help with some of the documentation. I have not used sphinx but should have some time to dig into it.

[5iver]

Is there the potential to have it configurable via the standard OH interface?

Yes. Scripted automation has access to all of the classes that a binding does. This is actually one if the three methods I'm working in for the Jython addon (not sure which will work or be accepted)...

1) Straight addon 2) Javascript script 3) NGRE configuration option

[CrazyIvan359]

@mjcumming you don't really need to learn Sphinx to write these docs. Everything you need to know about Sphinx you can find in the "Writing Documentation" page in this branch. As for what content needs work, I would say Examples/Design Patterns, I haven't touched those yet. Right now I'm working on the more in-depth guide to writing rules.

@openhab-5iver I agree about where to put it, Sphinx et al constitute quite a bulk of files. I think the actual content should remain in the main repo, but the theme and build could be pulled out to a docs/pages repo. We could then have parallel commit tags to allow the docs to be versioned with the library once that is setup (which seems imminent). Sphinx can't pull from a separate repo remotely, but it's just a Python program running on your computer when you get down to it, so it doesn't really care where the files are

I was thinking since we will have a single repo for all 3 languages, we should have a single set of docs. I've only thought about it a little, but we could have the home page have an intro to the repo as a whole and have links to each language's docs index.

JavaScript can be integrated easily enough, it wouldn't need to be a separate build even. I'll set it up once you get the js lib merged and we'll see how it looks. I haven't looked for a Groovy plugin yet.

The screen width setting is coming from the theme, I haven't looked into changing it yet but I'm sure it's not hard. It's definitely set at a fixed width though.

[Confectrician]

do you have any thoughts about what to do for Javascript documentation?

I have no preferences for now and also no knowledge about sphinx and the possibilities.

[5iver]

So... I have doc updates. I should delete the Docs-md and update the ones in Documentation, right?

[CrazyIvan359]

Yes, that's what we did in the rebase too

[5iver]

In the rebase, we ended up with both directories. I took a look but didn't see any updates that you might have done in Docs-md, but didn't want to blow it away in case you did update something in there. They looked out of date though.

[CrazyIvan359]

Oh yes, I see, I thought we had deleted Docs-md. You are correct, no changes were made in the branch to any of the old docs

[5iver]

I just pushed some doc updates. Now I'm going to try running the Sphinx script to update the generated docs.

[5iver]

Michael, what are your thoughts on including recommonmark? ATM, I'm thinking it would be best to keep everything in rst for consistency, but at the same time, it would be easier for those that know markdown to be able to use it. It could save some time in conversion too.

[CrazyIvan359]

I agree with all of those points lol. I think we should stick with RST for the library itself. Maybe we add the extension to make writing community docs easier? I think we shouldn't, learning RST isn't hard, it's block intended like Python and the rest is similar to md just with different symbols

[mjcumming]

@CrazyIvan359 @openhab-5iver - have read through a lot of the documentation. Looking great. Awesome work.