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!

The Features

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.

A New 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 yardoc and 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

For large readmes and extra files, sifting through all the text would be easier with a Table of Contents. Unfortunately most markup libraries lack support for this kind of thing. Fortunately, YARD now uses Javascript to automatically generate ToCs on file pages so that you can navigate those files much more easily and not worry about generating this manually.

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.