JSDoc for Rails 3

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.

Installation

Edit your Gemfile and add this line

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

Then run

bundle install

Next you need to copy the static assets (images, javascript and stylesheet) and also generate the migrations to create the JSDoc tables. They are all prefixed with ‘jsdoc_’ so shouldn’t conflict with anything you already have.

rails g jsdoc

Migrate your database

rake db:migrate

Loading the data

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

Configuration

There are 2 configuration options you can set. You specify them in an initializer. i.e. A file named config/initializers/jsdoc.rb

The first option is to specify the URL path the documentation will live at

Jsdoc::Engine.mount_point = '/documentation'

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

Jsdoc::Engine.source_path = 'jsdoc/source'

Creating views

Welcome Page

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

Header

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

Adding Stylesheets

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' %>

Everything else

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/