jsduck 4.6.1 → 4.6.2

data/lib/jsduck/guides.rb

@@ -5,6 +5,7 @@ require 'jsduck/util/null_object'
 require 'jsduck/logger'
 require 'jsduck/grouped_asset'
 require 'jsduck/util/html'
+require 'jsduck/img/dir'
 require 'fileutils'
 
 module JsDuck
@@ -39,6 +40,7 @@ module JsDuck
     def load_all_guides
       each_item do |guide|
         guide["url"] = resolve_url(guide)
+        guide[:filename] = guide["url"] + "/README.md"
         guide[:html] = load_guide(guide)
       end
     end
@@ -52,22 +54,29 @@ module JsDuck
 
     def load_guide(guide)
       return Logger.warn(:guide, "Guide not found", guide["url"]) unless File.exists?(guide["url"])
-
-      guide_file = guide["url"] + "/README.md"
-
-      return Logger.warn(:guide, "Guide not found", guide_file) unless File.exists?(guide_file)
+      return Logger.warn(:guide, "Guide not found", guide[:filename]) unless File.exists?(guide[:filename])
 
       begin
-        @formatter.doc_context = {:filename => guide_file, :linenr => 0}
-        @formatter.img_path = "guides/#{guide["name"]}"
-
-        return add_toc(guide, @formatter.format(Util::IO.read(guide_file)))
+        return format_guide(guide)
       rescue
         Logger.fatal_backtrace("Error while reading/formatting guide #{guide['url']}", $!)
         exit(1)
       end
     end
 
+    def format_guide(guide)
+      @formatter.doc_context = {:filename => guide[:filename], :linenr => 0}
+      @formatter.images = Img::Dir.new(guide["url"], "guides/#{guide["name"]}")
+      html = add_toc(guide, @formatter.format(Util::IO.read(guide[:filename])))
+
+      # Report unused images (but ignore the icon files)
+      @formatter.images.get("icon.png")
+      @formatter.images.get("icon-lg.png")
+      @formatter.images.report_unused
+
+      return html
+    end
+
     def write_guide(guide, dir)
       return unless guide[:html]
 

data/lib/jsduck/html_stack.rb

@@ -4,18 +4,6 @@ module JsDuck
 
   # Tracks opening and closing of HTML tags, with the purpose of
   # closing down the unfinished tags.
-  #
-  # Synopsis:
-  #
-  #     tags = HtmlStack.new
-  #     # open and close a bunch of tags
-  #     tags.open("a")
-  #     tags.open("b")
-  #     tags.close("b")
-  #
-  #     # ask which tags still need to be closed
-  #     tags.close_unfinished --> "</a>"
-  #
   class HtmlStack
 
     # Initializes the stack with two optional parameters:
@@ -28,18 +16,23 @@ module JsDuck
       @open_tags = []
     end
 
-    # Registers opening of a tag.  Returns the tag.
-    def open(tag)
-      @open_tags.unshift(tag) unless void?(tag)
-      tag
+    # Scans an opening tag in HTML using the passed in StringScanner.
+    def open(s)
+      s.scan(/</) + push_tag(s.scan(/\w+/)) + s.scan_until(/>|\Z/)
     end
 
-    # Registers closing of a tag.  Returns the tag.
-    def close(tag)
-      if @open_tags.include?(tag)
-        # delete the most recent unclosed tag in our tags stack
-        @open_tags.delete_at(@open_tags.index(tag))
-      end
+    # Scans a closing tag in HTML using the passed in StringScanner.
+    def close(s)
+      s.scan(/<\//)
+      tag = s.scan(/\w+/)
+      s.scan(/>/)
+
+      pop_tags(tag).map {|t| "</#{t}>" }.join
+    end
+
+    # Registers opening of a tag.  Returns the tag.
+    def push_tag(tag)
+      @open_tags.push(tag) unless void?(tag)
       tag
     end
 
@@ -48,22 +41,43 @@ module JsDuck
       @open_tags.include?(tag)
     end
 
-    # Returns HTML for closing the still open tags.
-    # Also prints warnings for all the unclosed tags.
-    def close_unfinished
-      return "" if @open_tags.length == 0
+    private
+
+    # Registers closing of a tag.  Returns all the tags that need to
+    # be closed at that point.
+    def pop_tags(tag)
+      if !@open_tags.include?(tag)
+        if @ignore_html[tag]
+          return [tag]
+        else
+          warn_unopened(tag)
+          return []
+        end
+      end
 
-      warn_unfinished
+      popped = []
+      begin
+        popped << t = @open_tags.pop
+        if t != tag
+          warn_unclosed(t)
+        end
+      end until t == tag
 
-      @open_tags.map {|tag| "</#{tag}>" }.join
+      popped
     end
 
-    private
+    def warn_unopened(*tags)
+      warn("Unopened HTML tag", tags)
+    end
+
+    def warn_unclosed(*tags)
+      warn("Unclosed HTML tag", tags)
+    end
 
-    def warn_unfinished
+    def warn(msg, tags)
       ctx = @doc_context
-      tag_list = @open_tags.map {|tag| "<#{tag}>" }.join(", ")
-      Logger.warn(:html, "Unclosed HTML tag: #{tag_list}", ctx[:filename], ctx[:linenr])
+      tag_list = tags.map {|tag| "<#{tag}>" }.join(", ")
+      Logger.warn(:html, "#{msg}: #{tag_list}", ctx[:filename], ctx[:linenr])
     end
 
     def void?(tag)

data/lib/jsduck/img/dir.rb

@@ -0,0 +1,94 @@
+require 'dimensions'
+require 'jsduck/logger'
+
+module JsDuck
+  module Img
+
+    # Looks up images from a directory.
+    class Dir
+      def initialize(full_path, relative_path)
+        @full_path = full_path
+        @relative_path = relative_path
+        @images = {}
+      end
+
+      # Retrieves hash of information for a given relative image
+      # filename.  It will have the fields:
+      #
+      # - :filename - the same as the parameter of this method
+      # - :full_path - actual path in the filesystem.
+      # - :relative_path - relative path to be used inside <img> tag.
+      # - :width - Image width
+      # - :height - Image height
+      #
+      # When the image is not found, returns nil.
+      def get(filename)
+        img = scan_img(filename)
+        if img
+          @images[filename] = img
+        end
+        img
+      end
+
+      # Returns all used images.
+      def all_used
+        @images.values
+      end
+
+      # Print warnings about all unused images.
+      def report_unused
+        scan_for_unused_images.each {|img| warn_unused(img) }
+      end
+
+      private
+
+      def scan_img(filename)
+        full_path = File.join(@full_path, filename)
+        if File.exists?(File.join(@full_path, filename))
+          img_record(filename)
+        else
+          nil
+        end
+      end
+
+      # Scans directory for image files, building a hash of image files
+      # found in that directory.
+      def scan_for_unused_images
+        unused = []
+        ::Dir[@full_path+"/**/*.{png,jpg,jpeg,gif}"].each do |path|
+          filename = relative_path(@full_path, path)
+          unused << img_record(filename) unless @images[filename]
+        end
+        unused
+      end
+
+      def warn_unused(img)
+        Logger.warn(:image_unused, "Image not used.", img[:full_path])
+      end
+
+      def img_record(filename)
+        full_path = File.join(@full_path, filename)
+        width, height = Dimensions.dimensions(full_path)
+
+        return {
+          :filename => filename,
+          :relative_path => File.join(@relative_path, filename),
+          :full_path => full_path,
+          :width => width,
+          :height => height,
+        }
+      end
+
+      # Given a path to directory and a path to file, returns the path
+      # to this file relative to the given dir. For example:
+      #
+      #     base_path("/foo/bar", "/foo/bar/baz/img.jpg") --> "baz/img.jpg"
+      #
+      def relative_path(dir_path, file_path)
+        file_path.slice(dir_path.length+1, file_path.length)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/img/dir_set.rb

@@ -0,0 +1,39 @@
+require "jsduck/img/dir"
+require "jsduck/logger"
+require "fileutils"
+
+module JsDuck
+  module Img
+
+    # A collection if Img::Dir objects.
+    #
+    # Looks up images from directories specified through --images
+    # option.
+    #
+    # This class provides the same interface as Img::Dir, except that
+    # the constructor takes array of full_paths not just one.
+    class DirSet
+      def initialize(full_paths, relative_path)
+        @dirs = full_paths.map {|path| Img::Dir.new(path, relative_path) }
+      end
+
+      def get(filename)
+        @dirs.each do |dir|
+          if img = dir.get(filename)
+            return img
+          end
+        end
+        return nil
+      end
+
+      def all_used
+        @dirs.map {|dir| dir.all_used }.flatten
+      end
+
+      def report_unused
+        @dirs.each {|dir| dir.report_unused }
+      end
+    end
+
+  end
+end

data/lib/jsduck/img/writer.rb

@@ -0,0 +1,23 @@
+require "jsduck/logger"
+require "fileutils"
+
+module JsDuck
+  module Img
+
+    # Copies images to destination directory.
+    class Writer
+      # Takes an array of image records retrieved from
+      # Img::Dir#all_used or Img::DirSet#all_used and copies all of
+      # them to given output directory.
+      def self.copy(images, output_dir)
+        images.each do |img|
+          dest = File.join(output_dir, img[:filename])
+          Logger.log("Copying image", dest)
+          FileUtils.makedirs(File.dirname(dest))
+          FileUtils.cp(img[:full_path], dest)
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/inline/auto_link.rb

@@ -0,0 +1,106 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Inline
+
+    # Takes care of the auto-detection of links in text.
+    class AutoLink
+      # Sets up instance to work in context of particular class, so it
+      # knows that #blah is in context of SomeClass.
+      attr_accessor :class_context
+
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      attr_accessor :doc_context
+
+      def initialize(link_renderer)
+        @class_context = ""
+        @doc_context = {}
+        @relations = link_renderer.relations
+        @renderer = link_renderer
+        @magic_link_re = magic_link_re
+      end
+
+      # Looks input text for patterns like:
+      #
+      #  My.ClassName
+      #  MyClass#method
+      #  #someProperty
+      #
+      # and converts them to links, as if they were surrounded with
+      # {@link} tag. One notable exception is that Foo is not created to
+      # link, even when Foo class exists, but Foo.Bar is. This is to
+      # avoid turning normal words into links. For example:
+      #
+      #     Math involves a lot of numbers. Ext JS is a JavaScript framework.
+      #
+      # In these sentences we don't want to link "Math" and "Ext" to the
+      # corresponding JS classes.  And that's why we auto-link only
+      # class names containing a dot "."
+      #
+      def replace(input)
+        input.gsub(@magic_link_re) do
+          cls = $1 || $3
+          member = $2 || $4
+          replace_magic_link(cls, member)
+        end
+      end
+
+      private
+
+      # Generates regex for auto-linking class and member names in text.
+      def magic_link_re
+        ident_re = "(?:[A-Za-z_$][A-Za-z0-9_$]*)"
+        cls_re = "(#{ident_re}(?:\\.#{ident_re})*)"
+        ns_cls_re = "(#{ident_re}(?:\\.#{ident_re})+)"
+        member_re = "(?:#(#{ident_re}))"
+        /#{cls_re}#{member_re}|#{ns_cls_re}|#{member_re}/m
+      end
+
+      def replace_magic_link(cls, member)
+        if cls && member
+          if @relations[cls] && @renderer.get_matching_member(cls, {:name => member})
+            return @renderer.link(cls, member, cls+"."+member)
+          else
+            warn_magic_link("#{cls}##{member} links to non-existing " + (@relations[cls] ? "member" : "class"))
+          end
+        elsif cls
+          if @relations[cls]
+            return @renderer.link(cls, nil, cls)
+          else
+            cls2, member2 = split_to_cls_and_member(cls)
+            if @relations[cls2] && @renderer.get_matching_member(cls2, {:name => member2})
+              return @renderer.link(cls2, member2, cls2+"."+member2)
+            elsif cls =~ /\.(js|css|html|php)\Z/
+              # Ignore common filenames
+            else
+              warn_magic_link("#{cls} links to non-existing class")
+            end
+          end
+        else
+          if @renderer.get_matching_member(@class_context, {:name => member})
+            return @renderer.link(@class_context, member, member)
+          elsif member =~ /\A([A-F0-9]{3}|[A-F0-9]{6})\Z/i || member =~ /\A[0-9]/
+            # Ignore HEX color codes and
+            # member names beginning with number
+          else
+            warn_magic_link("##{member} links to non-existing member")
+          end
+        end
+
+        return "#{cls}#{member ? '#' : ''}#{member}"
+      end
+
+      def split_to_cls_and_member(str)
+        parts = str.split(/\./)
+        return [parts.slice(0, parts.length-1).join("."), parts.last]
+      end
+
+      def warn_magic_link(msg)
+        Logger.warn(:link_auto, msg, @doc_context[:filename], @doc_context[:linenr])
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/inline/img.rb

@@ -1,25 +1,24 @@
 require 'jsduck/util/html'
 require 'jsduck/logger'
+require 'pp'
 
 module JsDuck
   module Inline
 
     # Implementation of inline tag {@img}
     class Img
-      # Base path to prefix images from {@img} tags.
-      # Defaults to no prefix.
-      attr_accessor :base_path
-
-      # This will hold list of all image paths gathered from {@img} tags.
+      # Instance of Img::Dir or Img::DirSet that's used for looking up
+      # image information.
       attr_accessor :images
 
+      # Sets up instance to work in context of particular doc object.
+      # Used for error reporting.
+      attr_accessor :doc_context
+
       def initialize(opts={})
-        @tpl = opts[:img_tpl] || '<img src="%u" alt="%a"/>'
+        @tpl = opts[:img_tpl] || '<img src="%u" alt="%a" width="%w" height="%h"/>'
 
         @re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m
-
-        @base_path = nil
-        @images = []
       end
 
       # Takes StringScanner instance.
@@ -37,13 +36,22 @@ module JsDuck
 
       # applies the image template
       def apply_tpl(url, alt_text)
-        @images << url
+        img = @images.get(url)
+        if !img
+          Logger.warn(:image, "Image #{url} not found.", @doc_context[:filename], @doc_context[:linenr])
+          img = {}
+        end
+
         @tpl.gsub(/(%\w)/) do
           case $1
           when '%u'
-            @base_path ? (@base_path + "/" + url) : url
+            img[:relative_path]
           when '%a'
             Util::HTML.escape(alt_text||"")
+          when '%w'
+            img[:width]
+          when '%h'
+            img[:height]
           else
             $1
           end