-
-
Notifications
You must be signed in to change notification settings - Fork 70
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Improvement] Documentation Rewrite #90
Conversation
@openhab-5iver Check out this commit. I restructured the file structure so that the docs source is now in I have also got doc-source in the module working. The Modules toc will look for any |
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... 😄 |
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 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. |
Scott, are you working on a way to do a jython "binding"? |
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. |
@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! |
@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? |
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! |
Squash-merge, I'll have to read up on that. I see you've added a 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. |
@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... |
@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? |
@CrazyIvan359 I could help with some of the documentation. I have not used sphinx but should have some time to dig into it. |
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)...
|
@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. |
I have no preferences for now and also no knowledge about sphinx and the possibilities. |
bb2ae94
to
500714c
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some of the documentation and the directory structure was lost, so I'll be submitting a PR to your branch.
So... I have doc updates. I should delete the Docs-md and update the ones in Documentation, right? |
Yes, that's what we did in the rebase too |
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. |
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 |
I just pushed some doc updates. Now I'm going to try running the Sphinx script to update the generated docs. |
document core/rules.py start documenting core/triggers.py
Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
972dcd1
to
d3dc057
Compare
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Michael Murton <6764025+CrazyIvan359@users.noreply.github.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
Signed-off-by: Scott Rushworth <openhab@5iver.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a major rewrite of the documentation. It is a big improvement with lots of additions to the existing documentation. Expect some followup PRs for minor tweaks. Please take a look and let us know what you think!
@CrazyIvan359 @openhab-5iver - have read through a lot of the documentation. Looking great. Awesome work. |
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