Preview of YARD 0.6 Features

YARD 0.5.7 is currently in the works and is possibly a week or so from release. After that version is put out there (pending no serious issues), all “yardwork” will be exclusively dedicated to the 0.6 release. There are some really cool and exciting new features in 0.6, so I felt like blogging about them. Let’s go:

1. A Local Documentation Server

RubyGems has gem server to serve static docs of your gems. The problem here, again, is that to get these static .html files we need to force our users to generate docs when the gem installs, and this is often a painfully slow process (especially with behemoths like Rails). YARD takes a different approach to this, only parsing out the source and saving an intermediate dump file when a gem installs. This is pretty fast (~2 seconds under 1.9 for YARD’s codebase). Not only can a developer use this data to their heart’s content, but it allows YARD to generate HTML/PDF/LaTeX on demand, and that’s exactly what 0.6 is going to do.

The yard server command coming in 0.6 will generate HTML documentation for gems on demand from the parsed source (perhaps even parsing on demand). This means your CPU will never be used to generate static files that you never look at. If you only need to access 10% of the documentation of 1% of your gems, YARD will only generate that 0.1%. Big win.

Not to mention you get all the benefits a YARD template provides, including full class hierarchy, less obtrusive layouts, markdown support, and even full method/class name searching with the potential of having full-text searching in the future, since this is all running in a Webrick/Rack adapter.

All of this stuff is currently being ported from the existing yardoc.org/docs site, so it will basically look like that. The existing code is in the docserver branch of YARD’s github and is being tracked as gh-139.

2. Method Listing by Groups

We’ve seen this in Apple’s docs, doxygen docs and a few others. The ability to organize methods in a large class by functionality rather than alphabet is often far more helpful to your users. YARD 0.6 will be introducing a @group freeform tag to identify methods under a specific organizational header which will be used in the templates. Still working on the exact syntax of this one, trying to make it as easy to use and remove as much duplication as possible. This feature is being tracked as gh-143.

3. Generate Documentation for Single File Scripts

RDoc has a --one-file option that is occasionally used for small Ruby scripts. YARD has always lacked this option. Though it’s kind of simple to roll your own with templates, 0.6 will have built-in templates for generating a single HTML document. Not really sure what it’s going to look like just yet, but if you have ideas or want to help out, the feature is being tracked as gh-115.

4. New yard CLI executable

YARD is growing into a tool that does much more than just parse source. This means that having a single executable is not enough, and spreading out the functionality over multiple executables is just messy. YARD currently uses the yard-graph tool to generate Graphviz dot files. In YARD 0.6, all of these tools, including the new documentation server, will all be merged into a single executable called yard with respective subcommands (doc, graph, server, etc.). The goal here is to open this up for plugins to add commands just like they do in RubyGems without resorting to new executable names. And don’t worry, the yardoc executable will probably stick around for legacy support. This feature is being tracked as gh-140.

5. Improved Template APIs

If you’ve ever written or overridden a template in YARD you know that it can be hard to figure out what section to override with the sections command. YARD has a sections.place(:foo).before(:bar) idiom, but it does not help with subsections. In 0.6, the sections will be redesigned from being Array objects to a more proper tree-like structure in order to handle accessing subsections. Now instead of:

def init
  sections.first.last.place(:foo).before(:bar)
end

You will have the ability to do the following:

def init
  sections.first.subsections.place(:foo).before(:bar)
  # or even:
  sections.place(:foo).before_first(:bar)
end


The last method will look for any "bar" inside sections or subsections within the tree. All in all, this should make it more effective to override a template. This feature is being tracked as [gh-58][7].

6. Documentation for DSL Handlers and Other Use Cases

YARD packs in a lot of functionality, and many users have complained that they had to dig into source to find out how to do some relatively simple things like writing handlers for DSL syntaxes. Although YARD does have documentation on many things, including writing handlers in general, there are few “use-case specific” documents that describe how to do specific things with YARD. 0.6 will introduce improved documentation for some of these use cases, most importantly extending YARD for custom DSL syntaxes. It’s possible this may start as a project in the Github Wiki as a set of how-to guides.

So there they are, the major new features coming to 0.6. Let me know if you have any suggestions about other features.

The release plan for YARD 0.6 is: “soon”. It’s hard to say when it will be out, but things are certainly rolling in that direction.