RDoc::Rails

This package adds Rails-specific information to RDoc generated docs on Rails projects. It could be particularly useful for people wanting to document Rails applications for internal use within a team of developers. It includes RDoc::Parser::Rails based on RDoc::Parser::Ruby as well as RDoc::Generator::Railsfish based on RDoc::Generator::Darkfish

Installation

Currently, this is written as a Rails plugin, although I will look into packaging it as a gem as well. It works with RDoc version 2.4.3, the most current version as of August, 2009. I have tested it only with Rails 2.0, but I would expect it to work for projects written in earlier and later versions of Rails as well.

To install as a Rails plugin, try some variation on one of the following:

ruby script/plugin install git://github.com/chinasaur/rdoc_rails.git
ruby script/plugin install http://github.com/chinasaur/rdoc_rails.git
ruby script/plugin install http://github.com/chinasaur/rdoc_rails.git/

You may then need/want to rename the directory vendor/plugins/rdoc_rails.git/ to just rdoc_rails

After that, you should be good to go. The standard

> rake doc:app

or

> rake doc:reapp

should now run the Rails customized version of RDoc.

Features

Right now there are just two basic features above and beyond the standard Ruby RDoc:

  1. Documentation for ActiveRecord associations on Models

  2. Documentation for methods delegated to other models through the delegate method.

But the infrastructure is all there to make it straightforward to parse additional features in Rails code and generate documentation based on those parsings.

Suggested Features

  • named_scope parsing

  • validate_* parsing

  • before_* parsing

  • after_* parsing

  • attr_protected parsing

  • attr_accessible parsing

  • custom user grouping and parsing (probably more core rdoc)

Tests

  • Tests are in development

  • Both tests for Comment model’s belongs_to associations fail

    • one is polymorphic

    • the other has a redefined class_name and counter_cache => true

  • tests run, but I don’t parse the output yet

Contributing

I will try to document things better to make it easy for others to contribute additional documentation features. For now, get in touch if you have any questions and fork away.

License

Rdoc::Rails is released under a Creative Commons Attribution 3.0 United States License. Please credit me somewhere in your project’s documentation if you are using this.

Dev by Jake

Gemified with Jeweler

rake version:bump:patch

rake version:bump:minor rake version:bump:major

rake gemspec

rake install

rake release

This seems to be incompatible with the latest rdoc 3.4. Attempting to remedy. Still not working.