Local Copies of ruby-core, ruby-stdlib and Rails Documentation
A lot of people have been asking where they can get a local copy of the same documentation YARD generates for rubydoc.info for train/bus/plane rides. It’s actually relatively easy to generate on your own, but it’s not totally obvious, so I’m going to lay it out in this article. If you’re really lazy, you can even short circuit my whole spiel and just download the docs right at the bottom.
Remember, if you only plan on parsing the sources to use with `yard server`, pass `-n` to YARD if you want to avoid generatic static .html files. It will save you lots of processing time.
ruby-core
The ruby-core docs that we publish on rubydoc.info/docs/ruby-core is basically taken from the *.c files in MRI (whichever version you want). As I said, it’s fairly easy to do this yourself, but you do need your own copy of the Ruby sources, which not everyone has. Fortunately they’re pretty easy to find on ruby-lang.org. I like to use 1.9.2, which you can get like so:
curl -O ftp://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.2-p0.tar.gz
tar xvzf ruby-1.9.2-p0.tar.gz
cd ruby-1.9.2-p0
Now that we’re in the directory, just call YARD:
yardoc *.c
If you don't want to generate the static .html files, use `yardoc -n *.c`
That gets you a doc directory that you can move wherever you like. You also have the .yardoc directory to use with the YARD server. You can launch the YARD server from the same directory:
yard server
Browse to http://localhost:8808 to see the docs live.
ruby-stdlib
We did the core documentation for Ruby, but we might also want all of the stdlib; that is, the loads of libraries that Ruby comes packaged with (RubyGems, RDoc, JSON, REXML, etc.). To do this, we just need to re-run YARD in our same Ruby source tree, but on the lib and ext directories instead. Fortunately, YARD already knows to look for lib and ext, so we don’t actually need to pass any parameters, but let’s pass a few so that we don’t clobber our existing .yardoc and doc folders that we just created for the core docs. To specify a new .yardoc dir and HTML output folder, respectively, use:
yardoc -b .yardoc-stdlib -o doc-stdlib
Realize that this will take a really long time. The stdlib is rather large. Once it’s done, you should have your YARD dump in .yardoc-stdlib and your HTML files in doc-stdlib. I’d suggest using the YARD server for the stdlib, that way you don’t have to spend the really long time generating all the HTML files, and you can generate them on the fly for only the few that you look at.
Rails
This one used to be a little more complicated, because the Rails tree doesn’t follow the standard ‘lib’ structure that you see with most gems. Luckily Rails3 uses a .yardopts file to tell YARD what to do. For Rails 2.3.x you’ll have to do it manually, so check out the .yardopts Rails3 uses to see what to pass to yardoc. We’ll just do Rails3, cause it’s easier, and that’s where the future is. Again, we need rails for this, and we can check it out of git to grab it:
git clone git://github.com/rails/rails
cd rails
Do the same thing with YARD. This time, just run:
yardoc
It might take a few minutes, but it should eventually get you what you want.
Done!
You now have all the documentation that rubydoc.info has. You can do this on other projects or gems, but remember that you have yard server --gems if you want to inspect the docs for your locally installed gems (*), and that will automatically generate the docs for you if they haven’t been.
(*) The one gem this won't work on is ‘rails'. This is because rails is a meta-gem, and doesn't actually have any code in it. You can look at the docs for the individual active*/action* gems, but not all at once (which admittedly isn't as useful). This is why we did the manual yardoc stuff above and why I didn't just tell you to use the gem doc server.
As promised, here are the docs I generated for the three projects, including the .yardoc directories, nicely zipped up for you to grab:
Enjoy!
I'm Loren Segal, a programmer, Rubyist, author of