jsduck 3.0.pre2 → 3.0.pre3

data/lib/jsduck/options.rb

@@ -1,4 +1,5 @@
 require 'optparse'
+require 'jsduck/meta_tag_loader'
 
 module JsDuck
 
@@ -24,8 +25,8 @@ module JsDuck
     attr_accessor :videos
     attr_accessor :examples
     attr_accessor :categories_path
-    attr_accessor :inline_examples_dir
     attr_accessor :pretty_json
+    attr_accessor :images
     attr_accessor :link_tpl
     attr_accessor :img_tpl
     attr_accessor :export
@@ -37,6 +38,7 @@ module JsDuck
     attr_accessor :template_links
     attr_accessor :extjs_path
     attr_accessor :local_storage_db
+    attr_accessor :touch_examples_ui
     attr_accessor :ext_namespaces
 
     def initialize
@@ -64,15 +66,15 @@ module JsDuck
         "CSSStyleSheet",
         "CSSStyleRule",
         "Event",
+        # Special anything-goes type
+        "Mixed",
       ]
-      @meta_tags = [
-        {:name => "author", :title => "Author", :strip => / *<.*?> */},
-        {:name => "docauthor", :title => "Documentation author", :strip => / *<.*?> */},
-      ]
+      @meta_tags = []
+      @meta_tag_paths = []
 
       @warnings = true
       @verbose = false
-      @version = "3.0.pre2"
+      @version = "3.0.pre3"
 
       # Customizing output
       @title = "Sencha Docs - Ext JS"
@@ -85,22 +87,24 @@ module JsDuck
       @videos = nil
       @examples = nil
       @categories_path = nil
-      @inline_examples_dir = nil
       @pretty_json = false
+      @images = []
       @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>'
+      @img_tpl = '<p><img src="%u" alt="%a"></p>'
       @export = nil
       @seo = false
 
       # Debugging
-      @processes = nil
+      # Turn multiprocessing off by default in Windows
+      @processes = OS::windows? ? 0 : nil
       @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
       @template_dir = @root_dir + "/template-min"
       @template_links = false
       @extjs_path = "extjs/ext-all.js"
       @local_storage_db = "docs"
+      @touch_examples_ui = false
       @ext_namespaces = ["Ext"]
     end
 
@@ -111,8 +115,11 @@ module JsDuck
     end
 
     def parse!(argv)
-      create_option_parser.parse!(argv).each {|fname| read_filenames(fname) }
+      create_option_parser.parse!(argv).each do |fname|
+        read_filenames(canonical(fname))
+      end
       validate
+      @meta_tags = MetaTagLoader.new.load(@meta_tag_paths)
     end
 
     def create_option_parser
@@ -141,13 +148,10 @@ module JsDuck
           read_filenames(@root_dir + "/js-classes")
         end
 
-        opts.on('--meta-tags @name=Title,...', Array,
-          "Defines custom meta-data tags in addition to",
-          "@author and @docauthor.  Experimantal!", " ") do |tags|
-          tags.each do |t|
-            t = t.split(/=/)
-            @meta_tags << {:name => t[0].sub(/^@/, ""), :title => t[1]}
-          end
+        opts.on('--meta-tags=PATH',
+          "Path to Ruby file or directory with custom",
+          "meta-tag implementations. Experimantal!", " ") do |path|
+          @meta_tag_paths << path
         end
 
         opts.on('--no-warnings', "Turns off warnings.", " ") do
@@ -210,14 +214,17 @@ module JsDuck
           @categories_path = canonical(path)
         end
 
-        opts.on('--inline-examples=PATH', "Path to inline examples directory.", " ") do |path|
-          @inline_examples_dir = canonical(path)
-        end
-
         opts.on('--pretty-json', "Turn on pretty-printing of JSON.", " ") do
           @pretty_json = true
         end
 
+        opts.on('--images=PATH',
+          "Search path for including images referenced by",
+          "{@img} tag. Several paths can be specified by",
+          "using the option multiple times.", " ") do |path|
+          @images << canonical(path)
+        end
+
         opts.on('--link=TPL',
           "HTML template for replacing {@link}.",
           "Possible placeholders:",
@@ -258,7 +265,7 @@ module JsDuck
         # For debugging it's often useful to set --processes=0 to get deterministic results.
         opts.on('-p', '--processes=COUNT',
           "The number of parallel processes to use.",
-          "Defaults to the number of processors/cores.",
+          OS::windows? ? "Defaults to off in Windows." : "Defaults to the number of processors/cores.",
           "Set to 0 to disable parallel processing completely.", " ") do |count|
           @processes = count.to_i
         end
@@ -287,6 +294,11 @@ module JsDuck
           @local_storage_db = name
         end
 
+        opts.on('--touch-examples-ui',
+          "Use phone/tablet UI for examples.", " ") do
+          @touch_examples_ui = true
+        end
+
         opts.on('--ext-namespaces=Ext,Foo', Array,
           "Namespace(s) of ExtJS. Defaults to 'Ext'.", " ") do |ns|
           @ext_namespaces = ns
@@ -364,7 +376,7 @@ module JsDuck
 
     # Runs checks on the options
     def validate
-      if @input_files.length == 0
+      if @input_files.length == 0 && !@welcome && !@guides && !@videos && !@examples
         puts "You should specify some input files, otherwise there's nothing I can do :("
         exit(1)
       elsif @export != :stdout
@@ -377,13 +389,13 @@ module JsDuck
         elsif !File.exists?(File.dirname(@output_dir))
           puts "Oh noes!  The parent directory for #{@output_dir} doesn't exist."
           exit(1)
-        elsif !File.exists?(@template_dir + "/extjs")
+        elsif !@export && !File.exists?(@template_dir + "/extjs")
           puts "Oh noes!  The template directory does not contain extjs/ directory :("
           puts "Please copy ExtJS over to template/extjs or create symlink."
           puts "For example:"
           puts "    $ cp -r /path/to/ext-4.0.0 " + @template_dir + "/extjs"
           exit(1)
-        elsif !File.exists?(@template_dir + "/resources/css")
+        elsif !@export && !File.exists?(@template_dir + "/resources/css")
           puts "Oh noes!  CSS files for custom ExtJS theme missing :("
           puts "Please compile SASS files in template/resources/sass with compass."
           puts "For example:"

data/lib/jsduck/os.rb

@@ -0,0 +1,11 @@
+require 'rbconfig'
+
+module JsDuck
+
+  # Simple helper class to detect operating system
+  class OS
+    def self.windows?
+      RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+    end
+  end
+end

data/lib/jsduck/renderer.rb

@@ -5,16 +5,15 @@ module JsDuck
   # Ruby-side implementation of class docs Renderer.
   # Uses PhantomJS to run Docs.Renderer JavaScript.
   class Renderer
-    def initialize(options={})
-      @options = options
-    end
+    # List of meta-tag implementations
+    attr_accessor :meta_tags
 
     def render(cls)
         @cls = cls
 
         return [
           "<div>",
-            render_hierarchy,
+            render_sidebar,
             "<div class='doc-contents'>",
               render_private_class_notice,
               @cls[:doc],
@@ -37,38 +36,30 @@ module JsDuck
     end
 
     def render_meta_data
-      return if !@cls[:meta] || @cls[:meta].length == 0
-
-      html = ["<ul class='meta-data'>"]
-
-      @options[:meta_tags].each do |meta|
-        title = meta[:title]
-        items = @cls[:meta].find_all {|m| m[:name] == meta[:name]}.map {|m| m[:content] }
-        content = meta[:strip] ? items.map {|m| m.gsub(meta[:strip], "") } : items
-        if items.length > 0
-          html << "<li><strong>#{CGI.escapeHTML(title)}:</strong> #{CGI.escapeHTML(content.join(', '))}</li>"
+      @meta_tags.map do |tag|
+        contents = @cls[:meta][tag.name]
+        if contents
+          tag.to_html(contents)
+        else
+          nil
         end
       end
-
-      html << "</ul>"
-
-      html
     end
 
-    def render_hierarchy
-      has_parents = @cls[:extends] && @cls[:extends] != "Object"
-      has_alt_names = @cls[:alternateClassNames].length > 0
-      has_mixins = @cls[:superclasses].length > 0
-
-      return if !has_parents && !has_alt_names && !has_mixins
-
-      return [
-        '<pre class="hierarchy">',
+    def render_sidebar
+      items = [
         render_alternate_class_names,
         render_tree,
-        render_mixins,
-        '</pre>'
+        render_dependencies(:allMixins, "Mixins"),
+        render_dependencies(:requires, "Requires"),
+        render_dependencies(:uses, "Uses"),
+        render_files,
       ]
+      if items.compact.length > 0
+        return ['<pre class="hierarchy">', items, '</pre>']
+      else
+        return nil
+      end
     end
 
     def render_alternate_class_names
@@ -79,11 +70,23 @@ module JsDuck
       ]
     end
 
-    def render_mixins
-      return if @cls[:allMixins].length == 0
+    def render_dependencies(type, title)
+      return if !@cls[type] || @cls[type].length == 0
+      return [
+        "<h4>#{title}</h4>",
+        @cls[type].map {|name| "<div class='dependency'>#{render_link(name)}</div>" },
+      ]
+    end
+
+    def render_files
+      return if @cls[:files].length == 0 || @cls[:files][0][:filename] == ""
       return [
-        "<h4>Mixins</h4>",
-        @cls[:allMixins].map {|name| "<div class='mixin'>#{render_link(name)}</div>" },
+        "<h4>Files</h4>",
+        @cls[:files].map do |file|
+          url = "source/" + file[:href]
+          title = File.basename(file[:filename])
+          "<div class='dependency'><a href='#{url}' target='_blank'>#{title}</a></div>"
+        end
       ]
     end
 
@@ -177,7 +180,7 @@ module JsDuck
           "<div class='title'>",
             "<div class='meta'>",
               "<a href='#!/api/#{owner}' rel='#{owner}' class='definedIn docClass'>#{owner}</a><br/>",
-              "<a href='source/#{m[:href]}' target='_blank' class='viewSource'>view source</a>",
+              "<a href='source/#{m[:files][0][:href]}' target='_blank' class='viewSource'>view source</a>",
             "</div>",
             # method params signature or property type signature
             render_signature(m),

data/lib/jsduck/search_data.rb

@@ -11,7 +11,7 @@ module JsDuck
       docs.each do |cls|
         list << class_node(cls)
         [:members, :statics].each do |group|
-          [:cfg, :property, :method, :event].each do |type|
+          cls[group].each_key do |type|
             cls.members(type, group).each do |m|
               # skip inherited items and constructors
               if m[:owner] == cls.full_name && m[:name] != cls.short_name

data/lib/jsduck/source_file.rb

@@ -23,7 +23,9 @@ module JsDuck
       @links = {}
 
       merger = Merger.new
+      merger.filename = @filename
       @docs = parse.map do |docset|
+        merger.linenr = docset[:linenr]
         link(docset[:linenr], merger.merge(docset[:comment], docset[:code]))
       end
     end
@@ -38,9 +40,9 @@ module JsDuck
     def html_filename=(html_filename)
       @html_filename = html_filename
       @links.each_value do |line|
-        line.each do |doc|
-          doc[:html_filename] = @html_filename
-          doc[:href] = @html_filename + "#" + id(doc)
+        line.each do |link|
+          link[:file][:html_filename] = @html_filename
+          link[:file][:href] = @html_filename + "#" + id(link[:doc])
         end
       end
     end
@@ -55,8 +57,8 @@ module JsDuck
         line = CGI.escapeHTML(line)
         # wrap the line in as many spans as there are links to this line number.
         if @links[linenr]
-          @links[linenr].each do |doc|
-            line = "<span id='#{id(doc)}'>#{line}</span>"
+          @links[linenr].each do |link|
+            line = "<span id='#{id(link[:doc])}'>#{line}</span>"
           end
         end
         lines << line
@@ -90,9 +92,12 @@ module JsDuck
     # Returns the modified doc-object after done.
     def link(linenr, doc)
       @links[linenr] = [] unless @links[linenr]
-      @links[linenr] << doc
-      doc[:filename] = @filename
-      doc[:linenr] = linenr
+      file = {
+        :filename => @filename,
+        :linenr => linenr,
+      }
+      @links[linenr] << {:doc => doc, :file => file}
+      doc[:files] = [file]
       if doc[:tagname] == :class
         doc[:members][:cfg].each {|cfg| link(linenr, cfg) }
         doc[:members][:method].each {|method| link(linenr, method) }