RailsDoc

This is my project proposal for Google’s Summer of Code 2006.

Wish me good luck! Nope, didn’t make it.

Applicant Contact Information

Name: Christoffer Sawicki
E-mail: [email protected]
Jabber: See above.
IRC: Qerub at #ruby-lang (freenode)

Project Proposal

There are times when it could be useful to quickly get the big picture of how a Rails application works. That can be when you are looking at someone else’s code or when discussing your application with a co-developer. Another situation is when your own application has grown big enough to not fit in the head. The application is scattered across many instances and it requires time to puzzle it all together. I propose a project called RailsDoc that takes a Rails application and produces a report that contains a high-level view of the application. More specifically, the report will answer the following questions:

Controllers and Actions
  • What controllers and actions exist?
  • What does the inline documentation say they do?
  • What before/after filters are invoked?
  • How is the controller inheritance hierarchy?
Models
  • What models exist?
  • How they do they interact?
  • What methods does a model carry? What do they do?
  • In the case of ActiveRecord models:
    • How do the database tables look?
    • What relations have been setup?
    • What hooks are being used?
Data Flows Between Model ↔ Controller ↔ View
  • How do the controllers/actions interact?
  • What models does a controller use?
  • How do controllers/actions interact?
  • Where do forms send data?
  • What information is exported into a view?
Test Coverage
  • How well is every part of the application covered by tests?
Libraries
  • What libraries are being used?
  • Where is their documentation?

The report will consist of text and graphs presented through HTML. RailsDoc will work by first creating an in-memory representation of the application containing all the information that should be available in the report. The sources for this representation will be Ruby’s and Rails’ introspection features together with code analysis where needed. I believe in using external libraries, and some like RDoc and rcov will be particularly useful. Naturally, I also believe in writing reusable components where it makes sense and some parts of RailsDoc will definitely be of use when extracted into libraries. Experience has taught me that Ruby code is best written together with unit tests. Once I’ve fleshed out the basic structure I’ll do further development by first writing unit tests, to establish the expected behaviour.

Possible Milestones

  1. An in-memory representation of the relevant parts of the Rails application, where the source of the data is the application file tree and introspection.
  2. Output to HTML by transforming the representation tree.
  3. Gather information from code analysis of Ruby code.
  4. Output diagrams and schemes from the representation tree.
  5. Running ERB templates in a sandbox to gather information.
  6. Incorporation of rcov into the representation tree and output mechanism.

I expect to code RailsDoc in about ten weeks, with the milestones being spread out linearily.

Me

I’d love to make this idea a reality. I’ve been using Rails for over a year and have personally seen a need for a tool of this kind. In fact I began working on a tool like this0, but with a more limited scope, some time ago. It started as a quick hack one evening but got some extra care when other people began to use it. I consider this to be the perfect grow ground for free software; a personal need, the required skills and interest from third-parties. A stipend would give me the resources to devote all the needed time.

0 Rails Application Visualizer

Experience

I’ve been a passionate user of Ruby since I bought the Programming Ruby book about two years ago. Hearing nothing but praises about this language made me buy the book. Time has passed since then and I nowadays consider myself fluent in Ruby and use it whenever I can. Ruby might not be the most elegant language in existence, but it really shines when it comes to gettings things done well. Having such a powerful language in one’s hands and some time naturally generates some software. Feedalizer1 and Quickpackage2 are two simple, but still very useful applications that I decided to make public and that have found some users.

I’ve been into web development since the day when I was ten years old and read an article about HTML. Later I did some trivial Perl CGI-scripts and then discovered PHP and used it for lots of projects. But it wasn’t until I discovered Rails that web development became really fun. Together with a friend I recently founded a company that develops websites for smaller organizations and individuals. We’ve had a slow start but things are looking bright. We consider Rails to be one of our best weapons against our competitors.

I’ve been using free software almost exclusively for the last six years. I’ve been running Debian and KDE all the time, mostly because it’s the only computing environment I can stand. My interest in free software has mostly been centered around those two projects. I joined the KDE-Debian effort when it started, because I thought (and still think) that there are tons of improvements that can be done. KDE-Debian was later renamed to Kalyxo and I became a developer, mostly packaging KDE-related stuff for Debian. Kalyxo never became the success we, the developers, had hoped since there was too much talk and too little code. But it was a good experience anyway and I learned a lot about free software development.

1 Feedalizer

2 Quickpackage

Education

I finished upper secondary school last year, where I studied Natural Science with a specialization on Maths and Computer Science. The last year there I administrated one of the computer class rooms using self-written software and wrote my thesis about it. I’m currently studying Computer Science and Engineering at Lund University’s Faculty of Engineering3 and look forward to study there the next years.

3 Faculty of Engineering Lund University