Rannotate - Annotatable and Searchable Docs for Ruby Projects

What is it?

Rannotate is a rails application and rdoc generator that work together to provide user submitted notes for rdoc generated documentation. It is modeled after the successful online PHP documentation at www.php.net

Examples

Rannotated Rails API documetation: Rails API Documentation - Rannotated
Rannotated Ruby (1.8.4) API documentation: Ruby Docs - Rannotated

Features?

- Display and submit notes for any file, class, module, method and other code objects
- Search the entire documentation
- Host multiple versions of documentation for a library at the same time
- Diff between versions of a class or module to see what has changed between library versions
- Ruby syntax highlighting for notes
- Page caching for extremely high performance browsing of the documentation
- Administration interface that allows you to edit and delete submitted notes, ban IP ranges and upload new documentation
- Custom RDoc YAML generator

Who is it by

The main code monkey is Conor Hunt. You can email him at conor DOT hunt PLUS rannotate AT gmail DOT com

Rannotate has been through a couple of iterations and has received some contributions along the way.

Kudos:
* Guido Sohne for his excellent rakefile tasks and for some patches to help it work with Postgres
* Jamis Buck for his excellent rdoc template (Jamis Rdoc template). This got me started.
* Matias Pelenur contributed a SVN repository, search code, bug fixes and suggestions
* Justin Palmer contributed the start of a new site design with the beginnings of a new CSS template

How does it work?

Rannotate depends on a custom rdoc generator that creates YAML. The rails application imports this YAML into the DB to generate the documentation on the fly and allow for neat features like searching and user annotations.

Where do I get it?

See the install instructions below..

Where do I get help/submit bugs/suggestions?

Rannotate rubyforge site
Rannotate wiki
Rannotate forums
Rannotate bug/feature trackers

Installation

Step 0:
Install the syntax gem: gem install syntax (rannotate uses this to do ruby syntax highlighting).
Pull down the code from the git repo (via clone, export,)
git clone git://github.com/conorh/rannotate.git

Step 1:
Put the yaml_generator.rb file from the rdoc_extension directory into your rdoc generator directory which is: [RUBY_DIR]\lib\ruby\1.8\rdoc\generators\

Step 2:
Setup config\database.yml for your DB and run 'rake migrate'

Step 3:
Generate some rdoc for your application using:
rdoc --fmt=yaml --opname=appname-0.2.3 directory
NOTE: The output format must be appname-[major].[minor].[release] rannotate uses the filename when importing the documentation to figure out the name of the library and the version. Unfortunately the generator can only tell you this issue after the generation has finished :(

Step 4:
Create an admin login account
ruby script\console
>> User.create({:login => 'admin', :password => .., :password_confirmation => ..}).save

Step 5:
Start webrick for rannotate (going to the homepage will error until you upload docs)

Step 6:
Login to the administration section using the login you generated at step 4
Admin URL - http://server:3000/admin/

Step 6:
Go to the Upload Documentation section and select the appname-0.2.3.out file that was generated at step 3.

Step 7:
Open up the URL of the documentation http://server:3000/ and there it is!

Notes on generating docs for rails and ruby

There are several tasks in the Rannotate Rakefile to help generate the documentation for rails or ruby.

rake doc:api:rails will generate the docs for the current version of rails

These tasks will place the docs in the /doc directory

Troubleshooting:-
There are files within the Rails repository that are RHTML style templates but that have .rb endings. This causes RDoc to be confused. My documentation method above doesn't hit those files, so there is not a problem. Howerever if you try and RDoc everything you may see errors like:
/rails/railties/lib/rails_generator/generators/components/controller/templates/controller.rb:3:15: Expected class name or '<<'. Got RubyToken::TkLT: "<"
To avoid these errors you must exclude those directories with RDoc:
rdoc -x railties/lib/rails_generator/generators/*/*/templates

Notes on using CGI/FCGI instead of webrick:

1. The dispatch files are set to run the ruby interpreter from my home dir you will need to modify the #! at the top of each /public/dispatch* file.
2. I didn't check in the log files so you may need to create the log directory and the development.log/production.log files in it.
3. You need to make the public and log directories read/writable by your web server, chmod 755 log -R, chmod 755 public -r