Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Rails 3 plugin to support JSDoc documentation

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 app
Octocat-spinner-32 config
Octocat-spinner-32 db
Octocat-spinner-32 jsdoc-toolkit
Octocat-spinner-32 lib
Octocat-spinner-32 script
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Gemfile
Octocat-spinner-32 MIT-LICENSE
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 jsdoc-rails.gemspec
README.rdoc

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 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"

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

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/

Something went wrong with that request. Please try again.