jsdoc-rails 0.0.1

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle/
+log/*.log
+pkg/
+test/dummy/db/*.sqlite3
+test/dummy/log/*.log
+test/dummy/tmp/
+rdoc/
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+gemspec
+
+gem 'sqlite3-ruby', :require => 'sqlite3'

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 Ryan Williams
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,94 @@
+= 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/

data/Rakefile

@@ -0,0 +1,29 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Jsdoc'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/app/controllers/jsdoc/documentation_controller.rb

@@ -0,0 +1,48 @@
+module Jsdoc
+  class DocumentationController < ApplicationController
+    layout 'jsdoc/documentation_wrapper'
+
+    before_filter :get_root_symbols, :except => [:raw_source]
+
+    def index
+    end
+
+    def symbol
+      @symbol = Jsdoc::Symbol.where(:alias => params[:symbol_alias]).first
+    end
+
+    def source
+      @filename = params[:filename]
+      @source_code = get_source_code(@filename)
+    end
+
+    def raw_source
+      @filename = params[:filename]
+      render :text => get_source_code(@filename), :content_type => 'text/plain'
+    end
+
+    private
+
+      def get_source_code(filename)
+        if Jsdoc::Engine.source_path[0..0] == '/'
+          source_path = Jsdoc::Engine.source_path
+        else
+          source_root = File.expand_path(File.join(Rails.root, 'public', Jsdoc::Engine.source_path))
+        end
+        file_path = File.expand_path(File.join(source_root, filename))
+
+        # Protect against kiddies trying to access other parts of the filesystem
+        raise "Invalid path" unless file_path.start_with?(source_root)
+
+        return File.open(file_path).read
+      end
+
+      def get_root_symbols
+        @root_symbols = Jsdoc::Symbol.where(:member_of => nil)
+
+        if Jsdoc::Engine.no_global
+          @root_symbols = @root_symbols.where('name != ?', '_global_')
+        end
+      end
+  end
+end

data/app/helpers/jsdoc/documentation_helper.rb

@@ -0,0 +1,50 @@
+module Jsdoc::DocumentationHelper
+  def symbols
+    return Jsdoc::Symbol.order(:alias)
+  end
+
+  def namespaces
+    return Jsdoc::Symbol.namespaces
+  end
+
+  def anchorName(member)
+    anchor = ''
+
+    anchor += 'static_' if member.is_static
+    anchor += 'method_' if member.is_a?(Jsdoc::Function) and member.symbol.present?
+    anchor += 'property_' if member.is_a?(Jsdoc::Property)
+    anchor += member.name
+  end
+
+  def full_class_list
+    output = '<ul>'
+    Jsdoc::Symbol.where(:member_of => nil).each do |child|
+      output += '<li>' + link_to(list_namespace(child), jsdoc_symbol_path(child.alias)) + '</li>'
+    end
+    output += '</ul>'
+    return output.html_safe
+  end
+
+  def list_namespace(namespace)
+    output = namespace.name
+    if namespace.children.size > 0
+      output += '<ul>'
+      for child in namespace.children
+        output += '<li>' + link_to(list_namespace(child), jsdoc_symbol_path(child.alias)) + '</li>'
+      end
+      output += '</ul>'
+    end
+
+
+    return output.html_safe
+  end
+
+  def link_to_symbol(symbol_type)
+    return nil if symbol_type.blank?
+
+    symbol = Jsdoc::Symbol.where(:alias => symbol_type).first
+    return symbol_type if symbol.nil?
+
+    return link_to(symbol_type, symbol.alias)
+  end
+end

data/app/models/jsdoc/borrowed_function.rb

@@ -0,0 +1,7 @@
+module Jsdoc
+  class BorrowedFunction < ActiveRecord::Base
+    belongs_to :borrowed_to, :class_name => 'Jsdoc::Symbol'
+    belongs_to :borrowed_from, :class_name => 'Jsdoc::Symbol'
+    belongs_to :function
+  end
+end

data/app/models/jsdoc/borrowed_property.rb

@@ -0,0 +1,7 @@
+module Jsdoc
+  class BorrowedProperty < ActiveRecord::Base
+    belongs_to :borrowed_to, :class_name => 'Jsdoc::Symbol'
+    belongs_to :borrowed_from, :class_name => 'Jsdoc::Symbol'
+    belongs_to :property
+  end
+end

data/app/models/jsdoc/example.rb

@@ -0,0 +1,5 @@
+module Jsdoc
+  class Example < ActiveRecord::Base
+    belongs_to :example_for, :polymorphic => true
+  end
+end

data/app/models/jsdoc/function.rb

@@ -0,0 +1,21 @@
+module Jsdoc
+  class Function < ActiveRecord::Base
+    belongs_to :symbol
+    has_many :params
+    has_many :returns
+    has_many :requires
+    has_many :throws
+    has_many :sees, :as => 'see_for'
+    has_many :examples, :as => 'example_for'
+
+    has_many :borrowed_to_join, :class_name => 'Jsdoc::BorrowedFunction'
+    has_many :borrowed_to, :through => :borrowed_to_join
+
+    scope :private, where(:is_private => true)
+    scope :public, where(:is_private => false)
+    scope :method_types, where(:function_type => 'method')
+    scope :event_types, where(:function_type => 'event')
+
+    scope :for_symbol, lambda { |s| includes(:borrowed_to).where('symbol_id = :symbol_id OR (jsdoc_borrowed_functions.borrowed_to_id = :symbol_id)', :symbol_id => s.id) }
+  end
+end

data/app/models/jsdoc/param.rb

@@ -0,0 +1,7 @@
+module Jsdoc
+  class Param < ActiveRecord::Base
+    belongs_to :function
+
+    default_scope order('"order"')
+  end
+end

data/app/models/jsdoc/property.rb

@@ -0,0 +1,13 @@
+module Jsdoc
+  class Property < ActiveRecord::Base
+    belongs_to :symbol
+
+    has_many :borrowed_to_join, :class_name => 'Jsdoc::BorrowedProperty'
+    has_many :borrowed_to, :through => :borrowed_to_join
+
+    scope :private, where(:is_private => true)
+    scope :public, where(:is_private => false)
+
+    scope :for_symbol, lambda { |s| includes(:borrowed_to).where('symbol_id = :symbol_id OR jsdoc_borrowed_properties.borrowed_to_id = :symbol_id', :symbol_id => s.id) }
+  end
+end

data/app/models/jsdoc/require.rb

@@ -0,0 +1,5 @@
+module Jsdoc
+  class Require < ActiveRecord::Base
+    belongs_to :function
+  end
+end

data/app/models/jsdoc/return.rb

@@ -0,0 +1,5 @@
+module Jsdoc
+  class Return < ActiveRecord::Base
+    belongs_to :function
+  end
+end

data/app/models/jsdoc/see.rb

@@ -0,0 +1,4 @@
+module Jsdoc
+  class See < ActiveRecord::Base
+  end
+end

data/app/models/jsdoc/symbol.rb

@@ -0,0 +1,58 @@
+module Jsdoc
+  class Symbol < ActiveRecord::Base
+    belongs_to :constructor, :class_name => 'Jsdoc::Function'
+    has_many :examples, :as => 'example_for'
+
+    has_many :own_functions, :class_name => 'Jsdoc::Function'
+    has_many :own_properties, :class_name => 'Jsdoc::Property'
+
+    has_many :borrowed_functions_join,  :foreign_key => 'borrowed_to_id', :class_name => 'Jsdoc::BorrowedFunction'
+    has_many :borrowed_properties_join, :foreign_key => 'borrowed_to_id', :class_name => 'Jsdoc::BorrowedProperty'
+
+    has_many :borrowed_functions, :through => :borrowed_functions_join,  :source => :function
+    has_many :borrowed_properties, :through => :borrowed_properties_join, :source => :property
+
+    has_many :children, :class_name => 'Jsdoc::Symbol', :foreign_key => :member_of, :primary_key => :alias
+    has_many :subclasses, :class_name => 'Jsdoc::Symbol', :foreign_key => :extends, :primary_key => :alias
+
+    belongs_to :superclass, :class_name => 'Jsdoc::Symbol', :foreign_key => :extends, :primary_key => :alias
+
+    scope :namespaces, where(:symbol_type => 'namespace')
+    scope :classes, where(:symbol_type => 'class')
+    scope :functions, where(:symbol_type => 'function')
+
+    def functions
+      return Jsdoc::Function.for_symbol(self)
+    end
+
+    def properties
+      return Jsdoc::Property.for_symbol(self)
+    end
+
+    def requires
+      return [] if constructor.nil?
+      return constructor.requires
+    end
+
+    def inheritance_tree
+      branches = [self]
+      while branches.last.superclass
+        branches << branches.last.superclass
+      end
+
+      return branches
+    end
+
+    def public_members?
+      return true if properties.public.present?
+      return true if functions.public.present?
+      return false
+    end
+
+    def private_members?
+      return true if properties.private.present?
+      return true if functions.private.present?
+      return false
+    end
+  end
+end

data/app/models/jsdoc/throw.rb

@@ -0,0 +1,4 @@
+module Jsdoc
+  class Throw < ActiveRecord::Base
+  end
+end

data/app/views/jsdoc/documentation/_inheritance_tree_branch.html.erb

@@ -0,0 +1,12 @@
+<ul>
+  <li>
+    <% if @symbol == branches.last %>
+      <%= branches.pop.name %>
+    <% else %>
+      <%= link_to(branches.last.name, jsdoc_symbol_path(branches.pop.alias)) %>
+    <% end %>
+    <% if branches.size > 0 %>
+      <%= render :partial => 'inheritance_tree_branch', :locals => {:branches => branches} %>
+    <% end %>
+  </li>
+</ul>

data/app/views/jsdoc/documentation/_members_table.html.erb

@@ -0,0 +1,38 @@
+<% if members.size > 0 %>
+  <table class="members">
+    <thead>
+      <tr>
+        <th><%= member_type.capitalize %></th>
+        <th class="defined_by">Defined By</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% for m in members.sort{|x,y| x.name <=> y.name} %>
+        <tr id="<%= anchorName(m) %>" class="<%= m.symbol == @symbol ? 'own' : 'borrowed' %> <%= member_type.underscore %>">
+          <td>
+            <% if m.is_static %><span class="flag">&lt;static&gt;</span><% end %>
+            <% if m.respond_to?('is_constant') and m.is_constant %><span class="flag">&lt;constant&gt;</span><% end %>
+            <% if m.respond_to?('is_readable') and m.is_readable and !m.is_writable %><span class="flag">&lt;read-only&gt;</span><% end %>
+            <% if m.respond_to?('is_readable') and m.is_writable and !m.is_readable %><span class="flag">&lt;write-only&gt;</span><% end %>
+            <% if m.is_a?(Jsdoc::Property) %>
+              <%= link_to(m.name, '#' + anchorName(m), :class => 'member_link') %> : <%= m.property_type.blank? ? '*' : link_to_symbol(m.property_type) %>
+            <% elsif m.is_a?(Jsdoc::Function) %>
+              <%= link_to(m.name, '#' + anchorName(m), :class => 'member_link') %> <%= render :partial => 'param_list', :locals => {:params => m.params} %> : <span class="return_type"><%= m.returns.blank? ? 'void' : link_to_symbol(m.returns.first.return_type) %></span>
+            <% else %>
+              <%= m.name %>
+            <% end %>
+
+            <% if m.description.present? %>
+              <div class="description">
+                <%= raw(m.description) %>
+              </div>
+            <% end %>
+          </td>
+          <td><%= m.symbol == @symbol ? @symbol.name : link_to(m.symbol.name, jsdoc_symbol_path(m.symbol.alias) + "##{member_type.underscore}_#{m.name}") %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% else %>
+  This <%= @symbol.symbol_type.downcase %> has no <%= member_type.downcase.pluralize %>.
+<% end %>