jsduck 2.0.pre4 → 3.0.pre

data/lib/jsduck/renderer.rb

@@ -0,0 +1,315 @@
+require 'cgi'
+
+module JsDuck
+
+  # Ruby-side implementation of class docs Renderer.
+  # Uses PhantomJS to run Docs.Renderer JavaScript.
+  class Renderer
+    def render(cls)
+        @cls = cls
+
+        return [
+          "<div>",
+            render_hierarchy,
+            "<div class='doc-contents'>",
+              render_private_class_notice,
+              @cls[:doc],
+            "</div>",
+            "<div class='members'>",
+              render_member_sections,
+            "</div>",
+          "</div>",
+        ].flatten.compact.join
+    end
+
+    def render_private_class_notice
+      return if !@cls[:private]
+      return [
+        "<p class='private'><strong>NOTE</strong> ",
+        "This is a private utility class for internal use by the framework. ",
+        "Don't rely on its existence.</p>",
+      ]
+    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">',
+        render_alternate_class_names,
+        render_tree,
+        render_mixins,
+        '</pre>'
+      ]
+    end
+
+    def render_alternate_class_names
+      return if @cls[:alternateClassNames].length == 0
+      return [
+        "<h4>Alternate names</h4>",
+        @cls[:alternateClassNames].map {|name| "<div class='alternate-class-name'>#{name}</div>" },
+      ]
+    end
+
+    def render_mixins
+      return if @cls[:allMixins].length == 0
+      return [
+        "<h4>Mixins</h4>",
+        @cls[:allMixins].map {|name| "<div class='mixin'>#{render_link(name)}</div>" },
+      ]
+    end
+
+    # Take care of the special case where class has parent for which we have no docs.
+    # In that case the "extends" property exists but "superclasses" is empty.
+    # We still create the tree, but without links in it.
+    def render_tree
+      return if !@cls[:extends] || @cls[:extends] == "Object"
+      tree = ["<h4>Hierarchy</h4>"]
+
+      if @cls[:superclasses].length > 0
+        tree + render_class_tree(@cls[:superclasses].concat([@cls[:name]]), {:first => true, :links => true})
+      else
+        tree + render_class_tree([@cls[:extends], @cls[:name]], {:first => true})
+      end
+    end
+
+    def render_class_tree(superclasses, o)
+      return "" if superclasses.length == 0
+
+      name = superclasses[0]
+      return [
+        "<div class='subclass #{o[:first] ? 'first-child' : ''}'>",
+          superclasses.length > 1 ? (o[:links] ? render_link(name) : name) : "<strong>#{name}</strong>",
+          render_class_tree(superclasses.slice(1, superclasses.length-1), {:links => o[:links]}),
+        "</div>",
+      ]
+    end
+
+    def render_link(cls_name)
+        return "<a href='#!/api/#{cls_name}' rel='#{cls_name}' class='docClass'>#{cls_name}</a>"
+    end
+
+    def render_member_sections
+      sections = [
+        {:type => :cfg, :title => "Config options"},
+        {:type => :property, :title => "Properties"},
+        {:type => :method, :title => "Methods"},
+        {:type => :event, :title => "Events"},
+        {:type => :css_var, :title => "CSS Variables"},
+        {:type => :css_mixin, :title => "CSS Mixins"},
+      ]
+
+      # Skip rendering empty sections
+      sections.map do |sec|
+        members = @cls[:members][sec[:type]]
+        statics = @cls[:statics][sec[:type]]
+        if members.length > 0 || statics.length > 0
+          [
+            "<div id='m-#{sec[:type]}'>",
+              statics.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
+              "<h3 class='members-title'>#{sec[:title]}</h3>",
+              render_subsection(members, statics.length > 0 ? "Instance #{sec[:title]}" : nil),
+              render_subsection(statics, "Static #{sec[:title]}"),
+            "</div>",
+          ]
+        else
+          nil
+        end
+      end
+    end
+
+    def render_subsection(members, title)
+      return if members.length == 0
+      index = 0
+      return [
+        "<div class='subsection'>",
+          title ? "<div class='definedBy'>Defined By</div><h4 class='members-subtitle'>#{title}</h3>" : "",
+          members.map {|m| index += 1; render_member(m, index == 1) },
+        "</div>",
+      ]
+    end
+
+    def render_member(m, is_first)
+      # use classname "first-child" when it's first member in its category
+      first_child = is_first ? "first-child" : ""
+      # use classname "expandable" when member has shortened description
+      expandable = m[:shortDoc] ? "expandable" : "not-expandable"
+      # shorthand to owner class
+      owner = m[:owner]
+      # use classname "inherited" when member is not defined in this class
+      inherited = owner == @cls[:name] ? "not-inherited" : "inherited"
+
+      return [
+        "<div id='#{m[:tagname]}-#{m[:name]}' class='member #{first_child} #{inherited}'>",
+          # leftmost column: expand button
+          "<a href='#' class='side #{expandable}'>",
+            "<span>&nbsp;</span>",
+          "</a>",
+          # member name and type + link to owner class and source
+          "<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>",
+            "</div>",
+            # method params signature or property type signature
+            render_signature(m),
+          "</div>",
+          # short and long descriptions
+          "<div class='description'>",
+            "<div class='short'>",
+              m[:shortDoc] ? m[:shortDoc] : m[:doc],
+            "</div>",
+            "<div class='long'>",
+              render_long_doc(m),
+            "</div>",
+          "</div>",
+        "</div>",
+      ]
+    end
+
+    def render_signature(m)
+      expandable = m[:shortDoc] ? "expandable" : "not-expandable"
+
+      name = m[:name]
+      before = ""
+      if m[:tagname] == :method && m[:name] == "constructor"
+        before = "<strong class='constructor-signature'>new</strong>"
+        name = @cls[:name]
+      end
+
+      if m[:tagname] == :cfg || m[:tagname] == :property || m[:tagname] == :css_var
+        params = "<span> : #{m[:html_type]}</span>"
+      else
+        ps = m[:params].map {|p| render_short_param(p) }.join(", ")
+        params = "( <span class='pre'>#{ps}</span> )"
+        if m[:tagname] == :method && m[:return][:type] != "undefined"
+          params += " : " + m[:return][:html_type]
+        end
+      end
+
+      after = ""
+      if m[:protected]
+        after += "<strong class='protected-signature'>protected</strong>"
+      end
+      if m[:static]
+        after += "<strong class='static-signature'>static</strong>"
+      end
+      if m[:deprecated]
+        after += "<strong class='deprecated-signature'>deprecated</strong>"
+      end
+      if m[:tagname] == :cfg && !m[:optional]
+        after += "<strong class='required-signature'>required</strong>"
+      end
+
+      uri = "#!/api/#{m[:owner]}-#{m[:tagname]}-#{m[:name]}"
+
+      return [
+        before,
+        "<a href='#{uri}' class='name #{expandable}'>#{name}</a>",
+        params,
+        after
+      ]
+    end
+
+    def render_short_param(param)
+      p = param[:html_type] + " " + param[:name]
+      return param[:optional] ? "["+p+"]" : p
+    end
+
+    def render_long_doc(m)
+      doc = [m[:doc]]
+
+      if m[:default] && m[:default] != "undefined"
+        doc << "<p>Defaults to: <code>" + CGI.escapeHTML(m[:default]) + "</code></p>"
+      end
+
+      if m[:deprecated]
+        v = m[:deprecated][:version] ? "since " + m[:deprecated][:version] : ""
+        doc << [
+          "<div class='deprecated'>",
+          "<p>This #{m[:tagname]} has been <strong>deprecated</strong> #{v}</p>",
+          m[:deprecated][:text],
+          "</div>",
+        ]
+      end
+
+      doc << render_params_and_return(m)
+
+      doc
+    end
+
+    # Handles both rendering of method parameters and return value.
+    # Plus the rendering of object properties, which could also be
+    # functions in which case they too will be rendered with
+    # parameters and return value.
+    def render_params_and_return(item)
+      doc = []
+
+      if item[:params] && item[:params].length > 0
+        params = item[:params]
+      elsif item[:properties] && item[:properties].length > 0
+        params = item[:properties]
+        # If the name of last property is "return"
+        # remove it from params list and handle it separately afterwards
+        if params.last[:name] == "return"
+          ret = params.last
+          params = params.slice(0, params.length-1)
+        end
+      end
+
+      if params
+        if item[:type] == "Function" || item[:tagname] == :method || item[:tagname] == :event
+          doc << '<h3 class="pa">Parameters</h3>'
+        end
+        doc << [
+          "<ul>",
+          params.map {|p| render_long_param(p) },
+          "</ul>",
+        ]
+      end
+
+      if item[:return]
+        doc << render_return(item[:return])
+      elsif ret
+        doc << render_return(ret)
+      end
+
+      doc
+    end
+
+    def render_long_param(p)
+      return [
+        "<li>",
+          "<span class='pre'>#{p[:name]}</span> : ",
+          p[:html_type],
+          p[:optional] ? " (optional)" : "",
+          "<div class='sub-desc'>",
+            p[:doc],
+            p[:default] ? "<p>Defaults to: <code>#{CGI.escapeHTML(p[:default])}</code></p>" : "",
+            p[:properties] && p[:properties].length > 0 ? render_params_and_return(p) : "",
+          "</div>",
+        "</li>",
+      ]
+    end
+
+    def render_return(ret)
+      return [
+        "<h3 class='pa'>Returns</h3>",
+        "<ul>",
+          "<li>",
+            "<span class='pre'>#{ret[:html_type]}</span>",
+            "<div class='sub-desc'>",
+              ret[:doc],
+              ret[:properties] && ret[:properties].length > 0 ? render_params_and_return(ret) : "",
+            "</div>",
+          "</li>",
+        "</ul>",
+      ]
+    end
+  end
+
+end

data/lib/jsduck/source_writer.rb

@@ -51,8 +51,8 @@ module JsDuck
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>

data/lib/jsduck/type_parser.rb

@@ -0,0 +1,85 @@
+require 'strscan'
+
+module JsDuck
+
+  # Validates the syntax of type definitions
+  #
+  # Quick summary of supported types:
+  #
+  # - SomeType
+  # - Name.spaced.Type
+  # - Number[]
+  # - String/RegExp
+  # - Type...
+  #
+  # Details are covered in spec.
+  #
+  class TypeParser
+    # Allows to check the type of error that was encountered.
+    # It will be either of the two:
+    # - :syntax - type definition syntax is incorrect
+    # - :name - one of the names of the types is unknown
+    attr_reader :error
+
+    # When parsing was successful, then contains the output HTML - the
+    # input type-definition with types themselves replaced with links.
+    attr_reader :out
+
+    # Initializes the parser with hash of valid type names and doc_formatter.
+    def initialize(relations={}, formatter={})
+      @relations = relations
+      @formatter = formatter
+    end
+
+    def parse(str)
+      @input = StringScanner.new(str)
+      @error = :syntax
+      @out = []
+
+      # Return immediately if base type doesn't match
+      return false unless base_type
+
+      # Go through enumeration of types, separated with "/"
+      while @input.check(/\//)
+        @out << @input.scan(/\//)
+        # Fail if there's no base type after "/"
+        return false unless base_type
+      end
+
+      # The definition might end with an ellipsis
+      @out << "..." if @input.scan(/\.\.\./)
+
+      # Concatenate all output
+      @out = @out.join
+
+      # Success if we have reached the end of input
+      return @input.eos?
+    end
+
+    # The basic type
+    #
+    #     <ident> [ "." <ident> ]* [ "[]" ]
+    #
+    # dot-separated identifiers followed by optional "[]"
+    def base_type
+      type = @input.scan(/[a-zA-Z_]+(\.[a-zA-Z_]+)*/)
+
+      if !type
+        return false
+      elsif @relations[type]
+        @out << @formatter.link(type, nil, type)
+      elsif @relations.ignore?(type) || type == "undefined"
+        @out << type
+      else
+        @error = :name
+        return false
+      end
+
+      @out << "[]" if @input.scan(/\[\]/)
+
+      true
+    end
+
+  end
+
+end

data/lib/jsduck/videos.rb

@@ -0,0 +1,33 @@
+require 'jsduck/json_duck'
+
+module JsDuck
+
+  # Reads in videos JSON file
+  class Videos
+    def initialize
+      @videos = []
+    end
+
+    # Parses videos config file
+    def parse(filename)
+      @videos = JsonDuck.read(filename)
+    end
+
+    # Writes videos JSON file to a dir
+    def write(dir)
+      return if @videos.length == 0
+
+      FileUtils.mkdir(dir) unless File.exists?(dir)
+      # Write the JSON to output dir, so it's available in released
+      # version of docs and people can use it with JSDuck by themselves.
+      JsonDuck.write_json(dir+"/videos.json", @videos)
+    end
+
+    # Returns all videos as array
+    def to_array
+      @videos
+    end
+
+  end
+
+end

data/lib/jsduck/welcome.rb

@@ -0,0 +1,21 @@
+module JsDuck
+
+  # Reads in HTML file with content for welcome page
+  class Welcome
+    # Parses welcome HTML file
+    def parse(filename)
+      @html = IO.read(filename)
+    end
+
+    # Returns the HTML
+    def to_html
+      if @html
+        "<div id='welcome-content' style='display:none'>#{@html}</div>"
+      else
+        ""
+      end
+    end
+
+  end
+
+end