This plugin allows you to load your Javascript documentation (using jsdoc-toolkit) into your Rails 3 application’s database. This means you can easily create dynamic and searchable documentation.

Edit your Gemfile and add this line

gem 'jsdoc-rails', :git => 'git:https://github.com/RyanWilliams/jsdoc-rails.git', :require => 'jsdoc'

Then run

bundle install

Next you need to install the migrations into your main application.

rake jsdoc:install:migrations

Migrate your database

rake db:migrate

Finall, add the route to your config/routes.rb

mount Jsdoc::Engine => "/documentation"

The data is generated using jsdoc-toolkit 2.4.0. This is included and used automatically. This utility does require java to be in your system path to function properly.

To import the documentation directly into your database simply run:

rake jsdoc:import SRC=/path/to/your/javascript/code

If everything went to plan you can fire up the rails console and see a class

Jsdoc::Symbol.where(:symbol_type => 'class').first

If you wish to generate the data on one machine for use on another you can split this into two operations.

First write the data out:

rake jsdoc:output SRC=/path/to/your/javascript/code OUTPUT=data/mydocs.rb

Now copy the file to the machine you want to load the data onto and import it with:

rake jsdoc:load SRC=data/mydocs.rb

There are 2 configuration options you can set. You specify them in your application.rb file along with your other configuration options.

The first option is the file-system path where your javascript source code is. This is relative to the Rails ‘public’ folder or an absolute path. The files are only used for rendering the source code in the documentation.

config.jsdoc.source_path = 'jsdoc/source'

The second options is a flag to hide the global group in the documentation tree.

config.jsdoc.no_global = true

At the very least you’ll want to customise the welcome page. To do this you just need to create a view in your project named app/views/jsdoc/documentation/index.html.erb

The header lives in a partial at app/views/layouts/jsdoc/_header.html.erb. Replace it with anything you like.

The easiest way to add a stylesheet is to create a layout at app/views/layouts/jsdoc/documentation_wrapper.html.erb and fill it with:

<% content_for(:head) do %>
  <%= stylesheet_link_tag 'my_styles.css' %>
<% end %>
<%= render :file => 'layouts/jsdoc/documentation' %>

If you wish to customise the whole layout then your best option is to peek at the views in the plugin and override anything you need to. They all live in app/views/jsdoc/ and app/views/layouts/jsdoc/