Announcing YARD 0.6.0
Today I’m announcing the release of YARD 0.6.0, codenamed “The Cubic”. I wrote a few articles in the last 2 months about the upcoming features, and I’m proud to announce that all of those features are included in the release, and much more! In total, YARD has 13 new “major” feature additions and many more smaller changes and bug fixes. There’s plenty in YARD to look at, and it should be much more stable.
In addition to the functional changes, plenty more documentation was written for features new and old, and I’ve started writing high level user guides on how to tackle common tasks in YARD. This is all going to be posted on the *drumroll* brand spanking new website which goes live today!
But let’s talk about features. As I mentioned, there are at least 13 major changes in YARD 0.6. Here are a handful of them:
A Local Documentation Server with Live Previews
YARD 0.6 adds the ability to serve documentation for gems as well as the current project with
yard server. Just like
gem server in RubyGems, you can serve gem docs. The advantage to YARD’s server is that you don’t need to pre-generate the static docs (with a
gem install) before running the server. If you installed your gem with
--no-rdoc, YARD will just generate it on the fly!
The best part of this process is it takes almost no time, since it doesn’t actually generate any files until you access them. This means you can now start saving time by avoiding the long process of generating static RDoc (or even YARD) documentation at a gem install.
YARD also has the ability to do “live reloading” for projects you’re currently documenting. Classically, people would write documentation and then run the documentation tool to generate static files and then check that they were generated correctly. This is a really slow feedback loop, especially for large projects where HTML generation can take many seconds, if not minutes. YARD 0.5 helped alleviate this pain by adding
--incremental parsing to generate only the files that changed. YARD 0.6 takes this one step further using the new server technology by doing all of this work for you automatically. Now, instead of constantly running
yard -c on your code, you can run
yard server --reload and, with the server running in the background, simply edit your documentation and refresh the page to see the updates. You get instantaneous live previews for everything you change in a completely natural way.
yard Command Line Interface
There is now a “yard” commandline interface that can be used to access all pre-existing commands (like
yard graph), but can now also be extended with plugins to add more functionality. If you’re a plugin developer, this will make your plugins much easier for your users to use. You can check out this blog post about the
yard diff utility for an example of some of the new commands.
Note that although there are
yard equivalents, the
yri shortcuts are still going to hang around for the forseeable future.
Method Listing Can Be Organized into Groups
If you’ve ever seen Apple’s Objective-C documentation you probably saw that methods in a class are grouped according to their behaviour under various headings. Doxygen has this functionality too. Both of these systems are very helpful for large classes or modules that fall into logical or coincidental cohesion patterns. YARD now supports this grouping of methods through the
@group declaration, which is used as follows:
module Utilities # @group Manipulating a String # Documentation for reverse def reverse(string) end def rot13(string) end # @group File Handling def read(filename) end # @endgroup def not_in_a_group; end end
The above code would list all methods under their respective headings, except for our last method which will be included in the normal “Instance Methods” heading, because we used
@endgroup to stop the lexical grouping process.
Manipulate and Add Tags at Command Line
Tags can now be added at the command-line to customize your templates or add in your own custom meta-data to your code without having to write a plugin or customize any template files. If you want to store some “@request_method” tag in your documentation and also want it in your templates, you can do it with a simple command line switch:
yardoc --tag request_method:"Request Method"
And we can now document the following web code and see our results in our HTML docs:
class MyController < ApplicationController # @request_method POST def signup; end end
You can add many kinds of tags, including ones that specify types (like
@return), names (like
@param) or both. You can also specify “transitive” tags (like
@since) which apply to all descendents of a namespace. For instance, when we add a
@since 0.6.0 tag to a class, all methods in that class will now have that tag unless explicitly overridden.
Automatic Table of Contents
RubyDoc.info – Documentation Server for Gems & Github Projects
If you’ve used yardoc.org/docs or rdoc.info you may have seen that we were planning on merging the projects. Well, with Nick Plante‘s help, we are finally announcing the launching of the new combined next generation YARD documentation server site: RubyDoc.info:
The site leverages YARD’s new documentation server architecture to serve documentation dynamically, so you will see much faster loading time for new projects. It’s also open source, so you can hack away and help make it better. For more information about the project, see Nick Plante’s blog.
Documentation For All Gems
We also leverage the auto-generation of gems technology to, for the first time in the Ruby community’s history, are announcing the birth of a site that will host documentation for every single published RubyGem, ever. We sync directly with RubyGems.org on a daily basis to make sure we have the updated gem index, and using YARD’s auto-generation of gems, serve them all up dynamically on demand, for any version.
Thanks to the Contributors
This was a big release, and a lot got done. Thanks to all the contributors who made this happen, and thanks to all the people who use YARD or write plugins, the goal is to make documentation easier and better. Hopefully we’re on the right track.