RailRoad

RailRoad copied to clipboard

= RailRoad

RailRoad generates models and controllers diagrams in DOT language for a Rails application.

This is a patched version based on the original v0.5.0.

I (Peter Hoeg) am not trying to hijack Javier's project, but since he hasn't released any new versions since May '08, I figured I'd better put one out in order to make railroad work with rails v2.3.

= Usage

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

== Options

Common options: -b, --brief Generate compact diagram (no attributes nor methods) -s, --specify file1[,fileN] Specify given files only for the diagram (can take a glob pattern) -e, --exclude file1[,fileN] Exclude given files (can take a glob pattern) -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-magic Hide magic field names --hide-types Hide attributes type -j, --join Concentrate edges -m, --modules Include modules -p, --plugins-models Include plugins models -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

-M, --models                     Generate models diagram
-C, --controllers                Generate controllers diagram
-A, --aasm                       Generate "acts as state machine" 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).

= RailRoad as a rake task

(Thanks to Thomas Ritz, http://www.galaxy-ritz.de ,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 the following Ruby and Rails versions

== Ruby

• 1.8.5
• 1.8.7

== Rails

• 1.1.6 to 1.2.3
• 2.3.2 to 2.3.5

There are 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.

= Website and Project Home

http://railroad.rubyforge.org

= License

RailRoad is distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See LICENSE for details.

== Copyright

Copyright (c) 2007-2008 Javier Smaldone Copyright (c) 2009 Peter Hoeg

See LICENSE for details.

== Authors

See AUTHORS for details.