jsduck 0.6.1 → 2.0.pre

data/lib/jsduck/aliases.rb

@@ -0,0 +1,39 @@
+module JsDuck
+
+  class Aliases
+    def initialize(relations)
+      @relations = relations
+    end
+
+    def resolve_all
+      @relations.each do |cls|
+        cls.each_member do |member|
+          if member[:alias]
+            resolve(member)
+          end
+        end
+      end
+    end
+
+    # Copy over doc/params/return from original member to alias.
+    def resolve(al)
+      orig = find_original(al)
+      al[:doc] = al[:doc] + "\n\n" + orig[:doc]
+      al[:params] = orig[:params] if orig[:params]
+      al[:return] = orig[:return] if orig[:return]
+    end
+
+    # Given aliased member, finds the original member.
+    # If the original also happens to be an alias, continue recursively.
+    def find_original(al)
+      al_def = al[:alias]
+      orig = @relations[al_def[:cls]].get_member(al_def[:member], al_def[:type] || al[:tagname])
+      if orig[:alias]
+        find_original(orig)
+      else
+        orig
+      end
+    end
+  end
+
+end

data/lib/jsduck/app.rb

@@ -2,15 +2,20 @@ require 'rubygems'
 require 'jsduck/aggregator'
 require 'jsduck/source_file'
 require 'jsduck/source_writer'
+require 'jsduck/doc_formatter'
 require 'jsduck/class'
 require 'jsduck/tree'
 require 'jsduck/tree_icons'
-require 'jsduck/members'
+require 'jsduck/search_data'
 require 'jsduck/relations'
-require 'jsduck/page'
+require 'jsduck/aliases'
 require 'jsduck/exporter'
 require 'jsduck/timer'
 require 'jsduck/parallel_wrap'
+require 'jsduck/logger'
+require 'jsduck/guides'
+require 'jsduck/categories'
+require 'jsduck/jsonp'
 require 'json'
 require 'fileutils'
 
@@ -21,22 +26,41 @@ module JsDuck
     # These are basically input parameters for app
     attr_accessor :output_dir
     attr_accessor :template_dir
+    attr_accessor :guides_dir
+    attr_accessor :guides_order
+    attr_accessor :categories_path
+    attr_accessor :template_links
     attr_accessor :input_files
-    attr_accessor :verbose
     attr_accessor :export
     attr_accessor :link_tpl
     attr_accessor :img_tpl
     attr_accessor :ignore_global
+    attr_accessor :external_classes
+    attr_accessor :show_private_classes
+    attr_accessor :title
+    attr_accessor :footer
+    attr_accessor :extjs_path
+    attr_accessor :append_html
 
     def initialize
       @output_dir = nil
       @template_dir = nil
+      @guides_dir = nil
+      @guides_order = nil
+      @categories_path = nil
+      @template_links = false
       @input_files = []
-      @verbose = false
+      @warnings = true
       @export = nil
       @link_tpl = nil
       @img_tpl = nil
       @ignore_global = false
+      @external_classes = []
+      @show_private_classes = false
+      @title = "Ext JS API Documentation"
+      @footer = 'Generated with <a href="https://github.com/senchalabs/jsduck">JSDuck</a>.'
+      @extjs_path = "extjs/ext-all.js"
+      @append_html = ""
       @timer = Timer.new
       @parallel = ParallelWrap.new
     end
@@ -47,35 +71,71 @@ module JsDuck
       @parallel = ParallelWrap.new(:in_processes => count)
     end
 
+    # Sets warnings on or off
+    def warnings=(enabled)
+      Logger.instance.warnings = enabled
+    end
+
+    # Sets verbose mode on or off
+    def verbose=(enabled)
+      Logger.instance.verbose = enabled
+    end
+
     # Call this after input parameters set
     def run
+      # Set default templates
+      @link_tpl ||= '<a href="#/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
+      # Note that we wrap image template inside <p> because {@img} often
+      # appears inline within text, but that just looks ugly in HTML
+      @img_tpl ||= '<p><img src="doc-resources/%u" alt="%a"></p>'
+
       parsed_files = @timer.time(:parsing) { parallel_parse(@input_files) }
       result = @timer.time(:aggregating) { aggregate(parsed_files) }
       relations = @timer.time(:aggregating) { filter_classes(result) }
+      Aliases.new(relations).resolve_all
       warn_globals(relations)
       warn_unnamed(relations)
 
+      @guides = Guides.new(get_doc_formatter(relations), @guides_order)
+      if @guides_dir
+        @timer.time(:parsing) { @guides.parse_dir(@guides_dir) }
+      end
+
+      @categories = Categories.new(get_doc_formatter(relations), relations)
+      if @categories_path
+        @timer.time(:parsing) do
+          @categories.parse(@categories_path)
+          @categories.validate
+        end
+      end
+
       clear_dir(@output_dir)
       if @export == :json
         FileUtils.mkdir(@output_dir)
         init_output_dirs(@output_dir)
         @timer.time(:generating) { write_src(@output_dir+"/source", parsed_files) }
-        @timer.time(:generating) { write_json(@output_dir+"/output", relations) }
+        @timer.time(:generating) { write_classes(@output_dir+"/output", relations) }
       else
-        copy_template(@template_dir, @output_dir)
+        if @template_links
+          link_template(@template_dir, @output_dir)
+        else
+          copy_template(@template_dir, @output_dir)
+        end
+        create_index_html(@template_dir, @output_dir)
         @timer.time(:generating) { write_src(@output_dir+"/source", parsed_files) }
         @timer.time(:generating) { write_tree(@output_dir+"/output/tree.js", relations) }
-        @timer.time(:generating) { write_members(@output_dir+"/output/members.js", relations) }
-        @timer.time(:generating) { write_pages(@output_dir+"/output", relations) }
+        @timer.time(:generating) { write_search_data(@output_dir+"/output/searchData.js", relations) }
+        @timer.time(:generating) { write_classes(@output_dir+"/output", relations) }
+        @timer.time(:generating) { @guides.write(@output_dir+"/guides") }
       end
 
-      @timer.report if @verbose
+      @timer.report
     end
 
     # Parses the files in parallel using as many processes as available CPU-s
     def parallel_parse(filenames)
       @parallel.map(filenames) do |fname|
-        puts "Parsing #{fname} ..." if @verbose
+        Logger.instance.log("Parsing #{fname} ...")
         SourceFile.new(IO.read(fname), fname)
       end
     end
@@ -84,11 +144,12 @@ module JsDuck
     def aggregate(parsed_files)
       agr = Aggregator.new
       parsed_files.each do |file|
-        puts "Aggregating #{file.filename} ..." if @verbose
+        Logger.instance.log("Aggregating #{file.filename} ...")
         agr.aggregate(file)
       end
       agr.classify_orphans
       agr.create_global_class unless @ignore_global
+      agr.append_ext4_event_options
       agr.result
     end
 
@@ -98,28 +159,28 @@ module JsDuck
       classes = []
       docs.each do |d|
         if d[:tagname] == :class
-          classes << Class.new(d)
+          classes << Class.new(d) if !d[:private] || @show_private_classes
         else
           type = d[:tagname].to_s
           name = d[:name]
           file = d[:filename]
           line = d[:linenr]
-          puts "Warning: Ignoring #{type}: #{name} in #{file} line #{line}"
+          Logger.instance.warn("Ignoring #{type}: #{name} in #{file} line #{line}")
         end
       end
-      Relations.new(classes)
+      Relations.new(classes, @external_classes)
     end
 
     # print warning for each global member
     def warn_globals(relations)
       global = relations["global"]
       return unless global
-      [:cfg, :property, :method, :event].each do |type|
+      global[:members].each_key do |type|
         global.members(type).each do |member|
           name = member[:name]
           file = member[:filename]
           line = member[:linenr]
-          puts "Warning: Global #{type}: #{name} in #{file} line #{line}"
+          Logger.instance.warn("Global #{type}: #{name} in #{file} line #{line}")
         end
       end
     end
@@ -127,12 +188,12 @@ module JsDuck
     # print warning for each member with no name
     def warn_unnamed(relations)
       relations.each do |cls|
-        [:cfg, :property, :method, :event].each do |type|
-          cls[type].each do |member|
+        cls[:members].each_pair do |type, members|
+          members.each do |member|
             if !member[:name] || member[:name] == ""
               file = member[:filename]
               line = member[:linenr]
-              puts "Warning: Unnamed #{type} in #{file} line #{line}"
+              Logger.instance.warn("Unnamed #{type} in #{file} line #{line}")
             end
           end
         end
@@ -142,7 +203,7 @@ module JsDuck
     # Given all classes, generates namespace tree and writes it
     # in JSON form into a file.
     def write_tree(filename, relations)
-      tree = Tree.new.create(relations.classes)
+      tree = Tree.new.create(relations.classes, @guides)
       icons = TreeIcons.new.extract_icons(tree)
       js = "Docs.classData = " + JSON.generate( tree ) + ";"
       js += "Docs.icons = " + JSON.generate( icons ) + ";"
@@ -151,39 +212,19 @@ module JsDuck
 
     # Given all classes, generates members data for search and writes in
     # in JSON form into a file.
-    def write_members(filename, relations)
-      members = Members.new.create(relations.classes)
-      js = "Docs.membersData = " + JSON.generate( {:data => members} ) + ";"
+    def write_search_data(filename, relations)
+      search_data = SearchData.new.create(relations.classes)
+      js = "Docs.searchData = " + JSON.generate( {:data => search_data} ) + ";"
       File.open(filename, 'w') {|f| f.write(js) }
     end
 
-    # Writes documentation page for each class
-    # We do it in parallel using as many processes as available CPU-s
-    def write_pages(path, relations)
-      cache = {}
-      @parallel.each(relations.classes) do |cls|
-        filename = path + "/" + cls[:name] + ".html"
-        puts "Writing to #{filename} ..." if @verbose
-        page = Page.new(cls, relations, cache)
-        page.link_tpl = @link_tpl if @link_tpl
-        page.img_tpl = @img_tpl if @img_tpl
-        File.open(filename, 'w') {|f| f.write(page.to_html) }
-      end
-    end
-
-    # Writes JSON export file for each class
-    def write_json(path, relations)
-      formatter = DocFormatter.new
-      formatter.link_tpl = @link_tpl if @link_tpl
-      formatter.img_tpl = @img_tpl if @img_tpl
-      formatter.relations = relations
-      exporter = Exporter.new(relations, formatter)
+    # Writes JsonP export file for each class
+    def write_classes(path, relations)
+      exporter = Exporter.new(relations, get_doc_formatter(relations))
       @parallel.each(relations.classes) do |cls|
-        filename = path + "/" + cls[:name] + ".json"
-        puts "Writing to #{filename} ..." if @verbose
-        hash = exporter.export(cls)
-        json = JSON.pretty_generate(hash)
-        File.open(filename, 'w') {|f| f.write(json) }
+        filename = path + "/" + cls[:name] + ".js"
+        Logger.instance.log("Writing to #{filename} ...")
+        JsonP.write(filename, cls[:name].gsub(/\./, "_"), exporter.export(cls))
       end
     end
 
@@ -194,17 +235,35 @@ module JsDuck
       # updates all the doc-objects related to the file
       parsed_files.each do |file|
         html_filename = src.write(file.to_html, file.filename)
-        puts "Writing to #{html_filename} ..." if @verbose
+        Logger.instance.log("Writing to #{html_filename} ...")
         file.html_filename = File.basename(html_filename)
       end
     end
 
+    # Creates and initializes DocFormatter
+    def get_doc_formatter(relations)
+      formatter = DocFormatter.new
+      formatter.link_tpl = @link_tpl if @link_tpl
+      formatter.img_tpl = @img_tpl if @img_tpl
+      formatter.relations = relations
+      formatter
+    end
+
     def copy_template(template_dir, dir)
-      puts "Copying template files to #{dir}..." if @verbose
+      Logger.instance.log("Copying template files to #{dir}...")
       FileUtils.cp_r(template_dir, dir)
       init_output_dirs(dir)
     end
 
+    def link_template(template_dir, dir)
+      Logger.instance.log("Linking template files to #{dir}...")
+      FileUtils.mkdir(dir)
+      Dir.glob(template_dir + "/*").each do |file|
+        File.symlink(File.expand_path(file), dir+"/"+File.basename(file))
+      end
+      init_output_dirs(dir)
+    end
+
     def clear_dir(dir)
       if File.exists?(dir)
         FileUtils.rm_r(dir)
@@ -215,6 +274,19 @@ module JsDuck
       FileUtils.mkdir(dir + "/output")
       FileUtils.mkdir(dir + "/source")
     end
+
+    def create_index_html(template_dir, dir)
+      Logger.instance.log("Creating #{dir}/index.html...")
+      html = IO.read(template_dir+"/index.html")
+      html.gsub!("{title}", @title)
+      html.gsub!("{footer}", @footer)
+      html.gsub!("{extjs_path}", @extjs_path)
+      html.gsub!("{append_html}", @append_html)
+      html.gsub!("{guides}", @guides.to_html)
+      html.gsub!("{categories}", @categories.to_html)
+      FileUtils.rm(dir+"/index.html")
+      File.open(dir+"/index.html", 'w') {|f| f.write(html) }
+    end
   end
 
 end

data/lib/jsduck/categories.rb

@@ -0,0 +1,132 @@
+require 'jsduck/logger'
+require 'json'
+
+module JsDuck
+
+  # Reads in categories and outputs them as HTML div
+  class Categories
+    def initialize(doc_formatter, relations={})
+      @doc_formatter = doc_formatter
+      @relations = relations
+      @categories = []
+    end
+
+    # Parses categories in JSON file
+    def parse(path)
+      @categories = JSON.parse(IO.read(path))["categories"]
+    end
+
+    # Prints warnings for missing classes in categories file
+    def validate
+      listed_classes = {}
+
+      # Check that each class listed in overview file exists
+      @categories.each do |cat|
+        cat["groups"].each do |group|
+          group["classes"].each do |cls_name|
+            unless @relations[cls_name]
+              Logger.instance.warn("Class '#{cls_name}' in category '#{cat['name']}/#{group['name']}' not found")
+            end
+            listed_classes[cls_name] = true
+          end
+        end
+      end
+
+      # Check that each existing non-private class is listed in overview file
+      @relations.each do |cls|
+        unless listed_classes[cls[:name]] || cls[:private]
+          Logger.instance.warn("Class '#{cls[:name]}' not found in categories file")
+        end
+      end
+    end
+
+    # Returns HTML listing of classes divided into categories
+    def to_html
+      return "" if @categories.length == 0
+
+      html = @categories.map do |category|
+        [
+          "<div class='section classes'>",
+          "<h1>#{category['name']}</h1>",
+          render_columns(category['groups']),
+          "<div style='clear:both'></div>",
+          "</div>",
+        ]
+      end.flatten.join("\n")
+
+      return <<-EOHTML
+        <div id='categories-content' style='display:none'>
+            #{html}
+        </div>
+      EOHTML
+    end
+
+    def render_columns(groups)
+      align = ["lft", "mid", "rgt"]
+      i = -1
+      return split(groups, 3).map do |col|
+        i += 1
+        [
+          "<div class='#{align[i]}'>",
+          render_groups(col),
+          "</div>",
+        ]
+      end
+    end
+
+    def render_groups(groups)
+      return groups.map do |g|
+        [
+          "<h3>#{g['name']}</h3>",
+          "<div class='links'>",
+          g["classes"].map {|cls| @relations[cls] ? @doc_formatter.link(cls, nil, cls) : cls },
+          "</div>",
+        ]
+      end
+    end
+
+    # Splits the array of items into n chunks so that the sum of
+    # largest chunk is as small as possible.
+    #
+    # This is a brute-force implementation - we just try all the
+    # combinations and choose the best one.
+    def split(items, n)
+      if n == 1
+        [items]
+      elsif items.length <= n
+        Array.new(n) {|i| items[i] ? [items[i]] : [] }
+      else
+        min_max = nil
+        min_arr = nil
+        i = 0
+        while i <= items.length-n
+          i += 1
+          # Try placing 1, 2, 3, ... items to first chunk.
+          # Calculate the remaining chunks recursively.
+          cols = [items[0,i]] + split(items[i, items.length], n-1)
+          max = max_sum(cols)
+          # Is this the optimal solution so far? Remember it.
+          if !min_max || max < min_max
+            min_max = max
+            min_arr = cols
+          end
+        end
+        min_arr
+      end
+    end
+
+    def max_sum(cols)
+      cols.map {|col| sum(col) }.max
+    end
+
+    # Finds the total size of items in array
+    #
+    # The size of one item is it's number of classes + the space for header
+    def sum(arr)
+      header_size = 3
+      arr.reduce(0) {|sum, item| sum + item["classes"].length + header_size }
+    end
+
+  end
+
+end