README.rdoc in rails-erd-0.2.0 vs README.rdoc in rails-erd-0.3.0

- old
+ new

@@ -1,214 +1,40 @@ = Rails ERD - Generate Entity-Relationship Diagrams for Rails applications -Rails ERD is a Rails plugin that allows you to easily generate a diagram based -on your ActiveRecord models. The diagram gives an overview of how your -models are related. Having a diagram that describes your models is perfect -documentation for your application. +{Rails ERD}[http://rails-erd.rubyforge.org/] is a Rails plugin that allows +you to easily generate a diagram based on your Active Record models. The +diagram gives an overview of how your models are related. Having a diagram +that describes your models is perfect documentation for your application. The second goal of Rails ERD is to provide you with a tool to inspect your application's domain model. If you don't like the default output, it is very easy to use the API to build your own diagrams. -Rails ERD was created specifically for Rails 3. It uses ActiveRecord reflection -to figure out how your models are associated. For older Rails applications, -you may want to try Railroad[http://railroad.rubyforge.org/]. +Rails ERD was created specifically for Rails 3. It uses Active Record's +built-in reflection capabilities to figure out how your models are associated. -== Links +== Preview -Current documentation: -http://rails-erd.rubyforge.org/doc/ +Here's an example entity-relationship diagram that was generated by Rails ERD: -Source code at Github: -http://github.com/voormedia/rails-erd +http://rails-erd.rubyforge.org/examples/event-forms.png +== Learn more + Homepage: http://rails-erd.rubyforge.org/ -== Example output +Diagram gallery: +http://rails-erd.rubyforge.org/gallery.html -This is an example diagram from an actual Rails application. +Installation instructions: +http://rails-erd.rubyforge.org/install.html -http://rails-erd.rubyforge.org/examples/event-forms.png - -{Download generated PDF}[http://rails-erd.rubyforge.org/examples/event-forms.pdf] - -Typo is a blogging application built in Rails. This is an excerpt from the -diagram that was generated from the Rails 3 branch (which is currently still -in development). - -http://rails-erd.rubyforge.org/examples/typo-blog.png - -{Download complete diagram as PDF}[http://rails-erd.rubyforge.org/examples/typo-blog.pdf] - -== Getting started - -In its most simple form, Rails ERD is a plugin for Rails 3 that provides you -with a Rake task to create an Entity-Relationship Diagram. It depends on the -Graphviz[http://www.graphviz.org/] visualisation library. In order to create -PDF files (the default), you should install or compile Graphviz with support -for Pango and Cairo. - -For example, to install Graphviz with Homebrew: - - % brew install cairo pango graphviz - -Or with MacPorts: - - % sudo port install graphviz - -Next, install Rails ERD. Open your +Gemfile+, and add the following: - - group :development do - gem 'rails-erd' - end - -Tell Bundler to install Rails ERD: - - % bundle install - -You now have access to Rails ERD through Rake. Generate a new -Entity-Relationship Diagram for your Rails application: - - % rake erd - -All done! You will now have a file named <tt>ERD.pdf</tt> in your application root. - -== Customisation - -Rails ERD has several options that you can use to customise its behaviour. -All options can be provided on the command line. For example: - - % rake erd orientation=vertical exclude_timestamps=false - -exclude_foreign_keys:: Excludes foreign key columns from attribute lists. - Defaults to +true+. -exclude_primary_keys:: Excludes primary key columns from attribute lists. - Defaults to +true+. -exclude_timestamps:: Excludes timestamp columns (<tt>created_at/on</tt> and - <tt>updated_at/on</tt>) from attribute lists. Defaults - to +true+. -exclude_unconnected:: Excludes entities that are not connected to other - entities from the diagram. Defaults to +true+. -file_type:: The file type of the generated diagram. Defaults to +pdf+, which - is the recommended format. Other formats may render significantly - worse than a PDF file. The available formats depend on your installation - of Graphviz. -orientation:: The direction of the hierarchy of entities. Either +horizontal+ - or +vertical+. Defaults to +horizontal+. The orientation of the - PDF that is generated depends on the amount of hierarchy - in your models. -suppress_warnings:: When set to +true+, no warnings are printed to the - command line while processing the domain model. Defaults - to +false+. - -== Custom diagrams - -If you're completely unsatisfied with the diagrams that Rails ERD creates, -you can still use it to create your own diagrams. It provides you with an easy -way to create any kind of diagram based on your application's domain model. - -As an example, a diagram class that generates code that can be used with -yUML (http://yuml.me) can be as simple as: - - require "rails_erd/diagram" - - class YumlDiagram < RailsERD::Diagram - def process_relationship(rel) - return if rel.indirect? - - arrow = case - when rel.cardinality.one_to_one? then "1-1>" - when rel.cardinality.one_to_many? then "1-*>" - when rel.cardinality.many_to_many? then "*-*>" - end - - instructions << "[#{rel.source}] #{arrow} [#{rel.destination}]" - end - - def save - instructions * "\n" - end - - def instructions - @instructions ||= [] - end - end - -Only 18 lines of code! Then, to generate the diagram (example based on the -domain model of Gemcutter): - - YumlDiagram.create - #=> "[Rubygem] 1-*> [Ownership] - # [Rubygem] 1-*> [Subscription] - # [Rubygem] 1-*> [Version] - # [Rubygem] 1-1> [Linkset] - # [Rubygem] 1-*> [Dependency] - # [Version] 1-*> [Dependency] - # [User] 1-*> [Ownership] - # [User] 1-*> [Subscription] - # [User] 1-*> [WebHook]" - -{See what that would look like}[http://yuml.me/diagram/scruffy/class/%5BRubygem%5D%201-*%3E%20%5BOwnership%5D,%20%5BRubygem%5D%201-*%3E%20%5BSubscription%5D,%20%5BRubygem%5D%201-*%3E%20%5BVersion%5D,%20%5BRubygem%5D%201-1%3E%20%5BLinkset%5D,%20%5BRubygem%5D%201-*%3E%20%5BDependency%5D,%20%5BVersion%5D%201-*%3E%20%5BDependency%5D,%20%5BUser%5D%201-*%3E%20%5BOwnership%5D,%20%5BUser%5D%201-*%3E%20%5BSubscription%5D,%20%5BUser%5D%201-*%3E%20%5BWebHook%5D]. - -== Internal API - -Rails ERD also allows you to use its internal API to inspect your Rails domain -model. It is easy to generate alternative presentations of your Active Record -models this way. If used outside of Rails, install Rails ERD as a gem: - - % gem install rails-erd - -Suppose we have the following models: - - class User < ActiveRecord::Base - has_many :posts - has_many :comments - end - - class Post < ActiveRecord::Base - belongs_to :user - has_many :comments - end - - class Comment < ActiveRecord::Base - belongs_to :user - belongs_to :post - end - -Then you can inspect your domain model like this: - - require "rails_erd/domain" - - domain = RailsERD::Domain.generate - domain.entities - #=> [ #<RailsERD::Entity @model=Comment>, - # #<RailsERD::Entity @model=Post>, - # #<RailsERD::Entity @model=User> ] - - domain.entities.first.connected? - #=> true - - domain.relationships - #=> [ #<RailsERD::Relationship @source=Post @destination=Comment>, - # #<RailsERD::Relationship @source=User @destination=Comment>, - # #<RailsERD::Relationship @source=User @destination=Post> ] - - domain.relationships.first.destination - #=> Comment - - domain.relationships.first.mutual? - #=> true - - domain.relationships.first.cardinality - #=> RailsERD::Relationship::Cardinality::OneToMany - -The above is just a sample of what is possible. See the API documentation for -more details: +Internal API documentation: http://rails-erd.rubyforge.org/doc/ -Please note that before the 1.0 release, the API may change subtly between -minor versions. +Source code at Github: +http://github.com/voormedia/rails-erd == About Rails ERD Author: Rolf Timmermans (r.timmermans <i>at</i> voormedia.com)