RailRoad

Ruby on Rails diagrams generator

RailRoad is a class diagrams generator for Ruby on Rails applications. It's a Ruby script that loads the application classes and analyzes its properties (attributes, methods) and relationships (inheritance, model associations like has_many, etc.) The output is a graph description in the DOT language, suitable to be handled with tools like Graphviz.

RailRoad can produce:

• Model diagrams, showing both inheritance hierarchy and models associations. You can choose to show the model "content columns" and its types.
• Controller diagrams, showing inheritance hierarchy. You can include the controllers' methods, grouped by its visibility (public, protected, private.)

From the author: This is not an original idea. Rdoc generates DOT graphs from Ruby code, and there are some other tools intended to produce the same diagrams that RailRoad generates. It's just that none of these programs suited my needs so... I decided to make it myself (and play a little more with the Ruby's introspection capabilities.)

Run RailRoad on the Rails application's root directory. You can redirect its output to a .dot file or pipe it to the dot or neato utilities to produce a graphic. Model diagrams are intended to be processed using dot and controller diagrams are best processed using neato.

railroad [options] command

Common options

• -b, --brief
  Generate compact diagram (no attributes nor methods)
• -e, --exclude file1[,fileN]
  Exclude files (relative path to 'app/models/' or 'app/controllers/')
• -i, --inheritance
  Include inheritance relations
• -l, --label
  Add a label with diagram information (type, date, migration, version)
• -o, --output FILE
  Write diagram to file FILE
• -v, --verbose
  Enable verbose output (produce messages to STDOUT)

Models diagram options

• -a, --all
  Include all models (not only ActiveRecord::Base derived)
• --hide-types
  Hide attributes type
• -j, --join
  Concentrate edges
• -m, --modules
  Include modules
• -t, --transitive
  Include transitive associations (through inheritance)

Controllers diagram options

• --hide-public
  Hide public methods
• --hide-protected
  Hide protected methods
• --hide-private
  Hide private methods

Other options

• -h, --help
  Show this message
• --version
  Show version and copyright

Commands

(You must supply one of these)

• -M, --models
  Generate models diagram
• -C, --controllers
  Generate controllers diagram

Examples

• railroad -o models.dot -M
  Produces a models diagram to the file 'models.dot'
• railroad -a -i -o full_models.dot -M
  Models diagram with all classes showing inheritance relations
• railroad -M | dot -Tsvg > models.svg
  Model diagram in SVG format
• railroad -C | neato -Tpng > controllers.png
  Controller diagram in PNG format
• railroad -h
  Shows usage help

Processing DOT files

To produce a PNG image from model diagram generated by RailRoad you can issue the following command:

dot -Tpng models.dot > models.png

If you want to do the same with a controller diagram, use neato instead of dot:

neato -Tpng controllers.dot > controllers.png

If you want to produce SVG (vectorial, scalable, editable) files, you can do the following:

dot -Tsvg models.dot > models.svg
neato -Tsvg controllers.dot > controllers.svg

Important: There is a bug in Graphviz tools when generating SVG files that cause a text overflow. You can solve this problem editing (with a text editor, not a graphical SVG editor) the file and replacing around line 12 "font-size:14.00;" by "font-size:11.00;", or by issuing the following command (see "man sed"):

sed -i 's/font-size:14.00/font-size:11.00/g' file.svg

Note: For viewing and editing SVG there is an excellent opensource tool called Inkscape (similar to Adobe Illustrator.) For DOT processing you can also use Omnigraffle (on Mac OS X).

Simple SVG generation

In Unix-like operating systems, you can define the following shell scripts:

models2svg

#!/bin/bash
railroad $* -M | \
dot -Tsvg | \
sed 's/font-size:14.00/font-size:11.00/g'

controllers2svg

#!/bin/bash
railroad $* -C | \
neato -Tsvg | \
sed 's/font-size:14.00/font-size:11.00/g'

And then generate SVG files by issuing commands like:

models2svg -i -l -a -m  > models.svg
controllers2svg -i -l > controllers.svg

(Notice that the command, -M or -C, is not necessary.)

RailRoad as a rake task

(Thanks to Thomas Ritz for the code.)

In your Rails application, put the following rake tasks into 'lib/task/diagrams.rake':

namespace :doc do
  namespace :diagram do
    task :models do
      sh "railroad -i -l -a -m -M | dot -Tsvg | sed 's/font-size:14.00/font-size:11.00/g' > doc/models.svg"
    end

    task :controllers do
      sh "railroad -i -l -C | neato -Tsvg | sed 's/font-size:14.00/font-size:11.00/g' > doc/controllers.svg"
    end
  end

  task :diagrams => %w(diagram:models diagram:controllers)
end

Then, 'rake doc:diagrams' produces 'doc/models.svg' and 'doc/controllers.svg'.

Requirements

RailRoad has been tested with Ruby 1.8.5 and Rails 1.1.6 to 1.2.3 applications. There is no additional requirements (nevertheless, all your Rails application requirements must be installed).

In order to view/export the DOT diagrams, you'll need the processing tools from Graphviz.

The development has started at the end of March 2006. RailRoad has been tested in the personal Rails developments of its author as well as in many "big" opensourced Rails applications (like Typo) with satisfactory results.

But that the output produced by RailRoad suits its author needs, doesn't guarantee that it will make you happy too. If you have some bug report (or some kind of suggestion), please visit the project's page at RubyForge. Feedback is not only encouraged but greatly appreciated.

This are some example diagrams produced RailRoad. (Maybe not from the last version.)

From the author: I know the diagrams don't look pretty much like UML diagrams, but I prefer something closer to BON.

Depot

The Depot application is a well known example from the book "Agile Web Development with Rails". (What a better way of start testing RailRoad?)

Models diagram You can also see it in SVG format.

Controllers diagram You can also see it in SVG format.

rTPlan

rTPlan is an application for project task planning. Its release 0.4.0 has 6 models, 11 controllers and 550 code LOC.

Models diagram You can also see it in SVG format.

Controllers diagram You can also see it in SVG format.

Typo

Typo is a weblog system (one of the most successful opensource applications) developed with Rails. And it's also a big program: 26 controllers, 59 models and 5469 code LOC for the release 4.1.

The models diagrams are generated without the "--all" option, for omitting non-ActiveRecord::Base derived classes (just to get a clearer diagram.)

Models diagram You can also see it in SVG format.

Controllers diagram You can also see it in SVG format.

For complex systems, RailRoad can also generate brief diagrams.

Models diagram (brief version)

Controllers diagram (brief version)

For complex model diagrams, you can also omit the inheritance relations (not issuing the "--inheritance" flag).

Models diagram (brief version, no inheritance)

If you're using gem, you can install RailRoad by issuing:

gem install railroad

You can also get the full sources from the project repository at RubyForge.

RailRoad is developed by Javier Smaldone (as part of his experiments with RoR).

The program is licensed under the GNU General Public License (as free software).