jsdoc-rails 0.0.1

data/lib/generators/jsdoc/jsdoc_generator.rb

@@ -0,0 +1,71 @@
+require 'rails/generators'
+require 'rails/generators/migration'     
+
+class JsdocGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  def self.source_root
+    @source_root ||= File.join(File.dirname(__FILE__), 'templates')
+  end
+
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations
+      if @previous_migration_number
+        @previous_migration_number += 1
+      else
+        @previous_migration_number = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+      end
+
+      return @previous_migration_number.to_s
+    else
+      return "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+
+  def create_migration_files
+    migration_templates = File.join(File.dirname(__FILE__), 'templates/migrations/')
+
+    Dir.foreach(migration_templates) do |f|
+      next unless f.ends_with?('.rb')
+
+      optional_migration_template "migrations/#{f}", "db/migrate/#{f}"
+    end
+  end
+
+  def copy_static_assets
+    assets = ['public/images/jsdoc/', 'public/stylesheets/jsdoc/', 'public/javascripts/jsdoc/'];
+
+    assets.each do |a|
+      asset_dir = File.join(File.dirname(__FILE__), '../../../', a)
+      copy_dir(asset_dir, a)
+    end
+  end
+
+  private
+
+    def copy_dir(src, dst)
+      Dir.foreach(src) do |f|
+        next if %w(. ..).include?(f)
+        src_file = File.join(src, f)
+        dst_file = File.join(dst, f)
+
+        if File.directory?(src_file)
+          copy_dir(src_file, dst_file)
+        else
+          copy_file(src_file, dst_file)
+        end
+
+      end
+    end
+
+    def optional_migration_template(*args)
+      migration_template(*args)
+    rescue Exception => e
+      if e.message.include?('Another migration is already named')
+        puts "Skipping existing migration: #{args[1]}"
+        return
+      else
+        raise e
+      end
+    end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_borrowed_functions_table.rb

@@ -0,0 +1,19 @@
+class JsdocCreateBorrowedFunctionsTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_borrowed_functions do |t|
+      t.integer :borrowed_to_id
+      t.integer :borrowed_from_id
+      t.integer :function_id
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_borrowed_functions, :borrowed_from_id
+    add_index :jsdoc_borrowed_functions, :borrowed_to_id
+    add_index :jsdoc_borrowed_functions, :function_id
+  end
+
+  def self.down
+    drop_table :jsdoc_borrowed_functions
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_borrowed_properties_table.rb

@@ -0,0 +1,19 @@
+class JsdocCreateBorrowedPropertiesTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_borrowed_properties do |t|
+      t.integer :borrowed_to_id
+      t.integer :borrowed_from_id
+      t.integer :property_id
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_borrowed_properties, :borrowed_from_id
+    add_index :jsdoc_borrowed_properties, :borrowed_to_id
+    add_index :jsdoc_borrowed_properties, :property_id
+  end
+
+  def self.down
+    drop_table :jsdoc_borrowed_properties
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_examples_table.rb

@@ -0,0 +1,18 @@
+class JsdocCreateExamplesTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_examples do |t|
+      t.integer :example_for_id
+      t.string :example_for_type
+      t.text :code
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_examples, :example_for_id
+    add_index :jsdoc_examples, :example_for_type
+  end
+
+  def self.down
+    drop_table :jsdoc_examples
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_functions_table.rb

@@ -0,0 +1,33 @@
+class JsdocCreateFunctionsTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_functions do |t|
+      t.string :name
+      t.string :alias
+      t.string :member_of
+      t.integer :symbol_id
+      t.string :function_type
+      t.string :version
+      t.text :description
+      t.string :defined_in
+      t.string :since
+      t.string :author
+      t.boolean :is_private
+      t.boolean :is_inner
+      t.boolean :is_static
+      t.boolean :is_deprecated
+      t.text :deprecated_description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_functions, :symbol_id
+    add_index :jsdoc_functions, :function_type
+    add_index :jsdoc_functions, :name
+    add_index :jsdoc_functions, :alias
+    add_index :jsdoc_functions, :member_of
+  end
+
+  def self.down
+    drop_table :jsdoc_functions
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_params_table.rb

@@ -0,0 +1,24 @@
+class JsdocCreateParamsTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_params do |t|
+      t.integer :function_id
+      t.integer :order
+      t.string :name
+      t.string :default
+      t.boolean :is_optional
+      t.string :param_type
+      t.text :description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_params, :function_id
+    add_index :jsdoc_params, :name
+    add_index :jsdoc_params, :order
+    add_index :jsdoc_params, :param_type
+  end
+
+  def self.down
+    drop_table :jsdoc_params
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_properties_table.rb

@@ -0,0 +1,37 @@
+class JsdocCreatePropertiesTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_properties do |t|
+      t.string :name
+      t.string :alias
+      t.string :member_of
+      t.integer :symbol_id
+      t.string :property_type
+      t.string :version
+      t.text :description
+      t.string :defined_in
+      t.string :since
+      t.string :author
+      t.string :default
+      t.boolean :is_private
+      t.boolean :is_inner
+      t.boolean :is_static
+      t.boolean :is_constant
+      t.boolean :is_deprecated
+      t.boolean :is_readable
+      t.boolean :is_writable
+      t.text :deprecated_description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_properties, :symbol_id
+    add_index :jsdoc_properties, :property_type
+    add_index :jsdoc_properties, :name
+    add_index :jsdoc_properties, :alias
+    add_index :jsdoc_properties, :member_of
+  end
+
+  def self.down
+    drop_table :jsdoc_properties
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_requires_table.rb

@@ -0,0 +1,16 @@
+class JsdocCreateRequiresTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_requires do |t|
+      t.integer :function_id
+      t.text :require
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_requires, :function_id
+  end
+
+  def self.down
+    drop_table :jsdoc_requires
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_returns_table.rb

@@ -0,0 +1,18 @@
+class JsdocCreateReturnsTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_returns do |t|
+      t.integer :function_id
+      t.string :return_type
+      t.text :description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_returns, :function_id
+    add_index :jsdoc_returns, :return_type
+  end
+
+  def self.down
+    drop_table :jsdoc_returns
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_sees_table.rb

@@ -0,0 +1,18 @@
+class JsdocCreateSeesTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_sees do |t|
+      t.integer :see_for_id
+      t.string :see_for_type
+      t.text :description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_sees, :see_for_id
+    add_index :jsdoc_sees, :see_for_type
+  end
+
+  def self.down
+    drop_table :jsdoc_sees
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_symbols_table.rb

@@ -0,0 +1,31 @@
+class JsdocCreateSymbolsTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_symbols do |t|
+      t.string :name
+      t.string :alias
+      t.string :member_of
+      t.integer :constructor_id
+      t.string :symbol_type
+      t.string :version
+      t.text :description
+      t.string :defined_in
+      t.string :since
+      t.string :author
+      t.string :extends
+      t.boolean :is_deprecated
+      t.text :deprecated_description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_symbols, :name
+    add_index :jsdoc_symbols, :alias
+    add_index :jsdoc_symbols, :member_of
+    add_index :jsdoc_symbols, :symbol_type
+    add_index :jsdoc_symbols, :constructor_id
+  end
+
+  def self.down
+    drop_table :jsdoc_symbols
+  end
+end

data/lib/generators/jsdoc/templates/migrations/jsdoc_create_throws_table.rb

@@ -0,0 +1,18 @@
+class JsdocCreateThrowsTable < ActiveRecord::Migration
+  def self.up
+    create_table :jsdoc_throws do |t|
+      t.integer :function_id
+      t.string :throw_type
+      t.text :description
+
+      t.timestamps
+    end
+
+    add_index :jsdoc_throws, :function_id
+    add_index :jsdoc_throws, :throw_type
+  end
+
+  def self.down
+    drop_table :jsdoc_throws
+  end
+end

data/lib/jsdoc.rb

@@ -0,0 +1,3 @@
+module Jsdoc
+  require 'jsdoc/engine'  if defined?(Rails) && Rails::VERSION::MAJOR == 3
+end

data/lib/jsdoc/engine.rb

@@ -0,0 +1,30 @@
+require 'jsdoc'
+require 'rails'
+require 'action_controller'
+
+module Jsdoc
+  def self.table_name_prefix
+    'jsdoc_'
+  end
+
+  class Engine < Rails::Engine
+    @@mount_point = '/documentation'
+    cattr_accessor :mount_point
+    @@source_path = 'jsdoc/source'
+    cattr_accessor :source_path
+    @@no_global = true
+    cattr_accessor :no_global
+
+    # We can add all of the public assets from our engine and make them
+    # available to use.  This allows us to use javascripts, images, stylesheets
+    # etc.
+    initializer 'static assets' do |app|
+      app.middleware.use ::ActionDispatch::Static, "#{root}/public"
+    end
+ 
+
+    rake_tasks do
+      load 'jsdoc/railties/tasks.rake'
+    end
+  end
+end

data/lib/jsdoc/railties/tasks.rake

@@ -0,0 +1,89 @@
+def confirm(msg)
+  puts msg
+  STDIN.gets.strip == 'yes'
+end
+
+def wipe_data
+  msg  = " /!\\ WARNING /!\\ THIS OPERATION WILL WIPE OUT EVERYTHING FROM THE JSDOC-RAILS TABLES.\n"
+  msg += " /!\\ WARNING /!\\ To skip this step specify NOWIPE=true when calling this taks.\n"
+  msg += " /!\\ WARNING /!\\ If you're sure you want to continue, please type 'yes'."
+  unless confirm(msg)
+    puts "Data wipe cancelled"
+    return false 
+  end
+    
+  [Jsdoc::BorrowedFunction, Jsdoc::BorrowedProperty, Jsdoc::Example, Jsdoc::Function, Jsdoc::Param, Jsdoc::Property, Jsdoc::Require, Jsdoc::Return, Jsdoc::See, Jsdoc::Symbol, Jsdoc::Throw].each do |klass|
+  puts "Deleting everything for: #{klass.name}"
+    klass.delete_all
+  end
+
+  return true
+end
+
+def output_jsdocs(src, dst)
+  output_dir = File.dirname(dst)
+  output_file = File.basename(dst)
+
+  jsdoc_path = File.join(File.dirname(__FILE__), '../../../jsdoc-toolkit')
+
+  template_path = File.join(jsdoc_path, 'templates', 'jsdoc-rails')
+
+  puts "Reading from: #{ENV['SRC']}"
+  puts "Outputing to: #{File.join(output_dir, output_file)}"
+  system(%Q(cd "#{src.gsub('"', '\\"')}"; java -jar "#{jsdoc_path}/jsrun.jar" "#{jsdoc_path}/app/run.js" -r=100 -a -d="#{output_dir}" -D="outputFile:#{output_file}" -t=#{template_path} -- *))
+end
+
+namespace :jsdoc do
+  desc "Write a Ruby script containing all the JSDoc definitions which can be loaded directly into Rails. Specify with SRC=/path/to/javascript/, OUTPUT=db/jsdoc-data.rb"
+  task :output do
+    output = ENV['OUTPUT'] || 'db/jsdoc-data.rb'
+    output = File.join(Dir.pwd, output) unless output[0..0] == '/'
+    src = ENV['SRC']
+
+    if src.blank?
+      puts "You must specify the SRC variable pointing to the location of your javascript code"
+      return 1
+    end
+
+    output_jsdocs(src, output)
+  end
+end
+
+namespace :jsdoc do
+  desc "Load a Ruby script containing JSDoc data, as generated by 'rake jsdoc:output'. Specify with SRC=db/jsdoc-data.rb, NOWIPE=false"
+  task :load => :environment do
+    src = ENV['SRC'] || 'db/jsdoc-data.rb'
+
+    unless ENV['NOWIPE'].present? and ENV['NOWIPE'][0..0].downcase == 't'
+      unless wipe_data
+        puts "Data load cancelled"
+        return false
+      end
+    end
+    load(src)
+  end
+end
+
+namespace :jsdoc do
+  desc "Load all the JSDoc data from your Javascript source. Effectivly the same as running jsdoc:output then jsdoc:load. Specify with SRC=/path/to/javascript/, NOWIPE=false"
+  task :import => :environment do
+    src = ENV['SRC']
+
+    if src.blank?
+      puts "You must specify the SRC variable pointing to the location of your javascript code"
+      return 1
+    end
+
+    unless ENV['NOWIPE'].present? and ENV['NOWIPE'][0..0].downcase == 'f'
+      unless wipe_data
+        puts "Data load cancelled"
+        return false
+      end
+    end
+
+    tmpfile = Tempfile.new('jsdoc-rails')
+    output_jsdocs(src, tmpfile.path)
+    load(tmpfile.path)
+    tmpfile.close
+  end
+end