docs
docs copied to clipboard
rethinkdb
Generate docs for use with Dash
Dash is a hugely popular tool for OS X developers for quickly looking up documentation -- we should be able to generate a docset for it pretty easily (http://kapeli.com/docsets).
I looked into this (briefly) already -- I'm a Dash user myself.
The challenge is that ReQL isn't like other languages you'd drop into Dash, or even like other language-specific libraries/frameworks like Node or Rails -- what we really have are three libraries for three languages, and I don't think there's a way to implement the language switcher within Dash. Do we generate three docsets for "ReQL JavaScript," "ReQL Python" and "ReQL Ruby?" Generate one ReQL docset that lists each command three times? Merge the commands together? I suspect three separate docsets is probably the least worst option, both in terms of creation time and usability for developers, but I'm not sure what your take is on that.
:+1: would love to see this happen. I've actually tried myself a bunch of times, but it was surprisingly complicated without intimate RethinkDB docs knowledge.
It doesn't look like you would be the first to split up by language, e.g.
Given that there's precedent, we can definitely produce three docsets. We already have a script that generates docs for the Data Explorer, so hopefully it wouldn't be too hard to export to the Dash format as well.
Dash format is whatever you like really -- I would recommend HTML from your actual docs for the prettiest format possible, e.g. looking at the Ember docs within Dash:
You can see it's pretty much just a download of the Ember API Docs with the sidebar removed and interpolated by Dash directly.
I agree that we should do the HTML docs (we can keep the illustrations as well, which would be wonderful).
When I said "the Dash format", what I really mean is the Info.plist file and SQLite index (or any other relevant bits and pieces) to make Dash work -- I haven't researched it all, but there's a list on the page I linked to above. Thanks for all the input, @chrisvariety, we appreciate it!
There's a first pass at this at in the issue-541-dash-docs branch (2c4ff53141be595d8b5c3d72a238cd649e1a927b). Right now that creates a _dash top-level directory with the script and support files, and creates the docsets in a build directory under that.
Also, right now this requires Pandoc to be installed (it'll warn you if it isn't; it's in Homebrew) and zsh (which comes installed on OS X), although we can probably abstract out the zsh-specific bits. (I suspect that's only the filename munging.)
I haven't gone back to the branch mentioned way back in October and updated it in a while, but I'll look at updating it -- we might move it to another repository so it's more accessible.
Just as an update to those monitoring this, I do have an "unofficial" repository with a kind of Rube Goldberg-esque script that builds three docsets, one for each language. It requires you to install pandoc first and to have checked out the docs repository.
https://github.com/chipotle/reql-dash-build
We'll see about moving this into an "official" repository down the road, but if you're interested in testing it, you can see if the script works. (You will probably get a couple warnings.)
Is this issue still up? I'm a Dash user too and I would really appreciate the effort to put the docs officially on Dash. RethinkDB is the last piece of my stack that isn't on Dash yet.
Great work on the docs though. It is really easy to get started with RethinkDB.
It is still up, but it's been kind of shoved to the back burner due to other projects, unfortunately. We'd still like to get into the official Dash repository some day, but in the meantime you can build the doc sets yourself with the project I linked to in a previous comment. I just double-checked, and it still builds. (Still with two mysterious pandoc warnings when building JavaScript that I will eventually track down...)