Ruby Tools: Yard 0.4 Adds Live Doc Server, Gem Bundler Handles Dependencies

Posted by Werner Schuster on Nov 15, 2009

Sections

Development,

Operations & Infrastructure

Topics

RubyGems ,

Tools ,

Configuration Management ,

Ruby

Tags

Deployment ,

Yard ,

Documentation ,

RubyGems

YARD is a documentation generator for Ruby which adds a few features such as Javadoc-style metadata in comment strings and plugins.

The new YARD 0.4.0 contains improvements such as a revamped template system. A new feature allows to limit documentation generation to code that has certain metadata values.

A big new feature is the live documentation server:

[B]rand-spanking-new user comments system powered by DISQUS that is available on these individual method pages, allowing users to contribute extra information about methods in one place.

A public instance of the server is available at http://yardoc.org/docs with a list of project documentation already available, eg. Rails.

Gem Bundler is a new tool that makes it easier to manage Gem dependencies in a project and to control which Gems are required at runtime.

Yehuda Katz, one of the creators of Gem Bundler, explains the ideas behind the tool:

The bundler should allow the specification of all dependencies in a separate place from the application itself. In other words, it should be possible to determine the dependencies for an application without needing to start up the application. [..].
Once the dependencies are resolved, it should be possible to get the application up and running on a new system without needing to check Rubyforge (or gemcutter) again. This is especially important for compiled gems (it should be possible to get the list of required gems once and compile on remote systems as desired). [..]
Above all else, the bundler should provide a reproducible installation of Ruby applications. New gem releases or down remote servers should not be able to impact the successful installation of an application.

Dependencies are listed in a Gemfile and can either come from the default Gem sources or custom ones.

Dependencies can also be grouped into named environments. Environments are useful when the application needs to be run in different circumstances, eg. 'production', 'testing', etc. The Gems found by Gem Bundler can be required with Bundler.require_env for the default environment, or by passing in the name of the environment, eg. Bundler.require_env(:testing).

More thorough introductions are available іn an EngineYard blog post introducing Gem Bundler or Yehuda's introduction to Gem Bundler that goes into many details and explains how Gem Bundler integrates with Rails.

• Older >