Commit 003241df authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Implement --images option. 

Using this, JSDuck will automatically copy over images referenced
by {@img} tag.  No more need for extra copy task after running JSDuck.
parent 64cbc5ed

Rakefile

+5 −35
Original line number Diff line number Diff line
@@ -170,6 +170,8 @@ class JsDuckRunner 
      "--categories", "#{@sdk_dir}/extjs/docs/categories.json",

      "--output", "#{@out_dir}",

      "--builtin-classes",

      "--images", "#{@sdk_dir}/extjs/docs/resources",

      "--images", "#{@sdk_dir}/platform/docs/resources",

      "#{@sdk_dir}/extjs/src",

      "#{@sdk_dir}/platform/src",

      "#{@sdk_dir}/platform/core/src",
@@ -182,6 +184,7 @@ class JsDuckRunner 
      "--footer", "Ext JS 4.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",

      "--ignore-global",

      "--no-warnings",

      "--images", "#{@ext_dir}/docs/doc-resources",

      "--output", "#{@out_dir}",

      "#{@ext_dir}/src",

    ]
@@ -201,6 +204,7 @@ class JsDuckRunner 
      "--videos", "#{@sdk_dir}/touch/doc-resources/videos.json",

      "--output", "#{@out_dir}",

      "--external=google.maps.Map,google.maps.LatLng",

      "--images", "#{@sdk_dir}/touch/doc-resources",

      "#{@sdk_dir}/touch/resources/themes/stylesheets/sencha-touch/default",

    ]
@@ -221,6 +225,7 @@ class JsDuckRunner 
      "--videos", "#{@sdk_dir}/touch/docs/videos.json",

      "--output", "#{@out_dir}",

      "--external=google.maps.Map,google.maps.LatLng",

      "--images", "#{@sdk_dir}/touch/docs/resources",

      "#{@sdk_dir}/touch/resources/themes/stylesheets/sencha-touch/default",

    ]
@@ -332,32 +337,6 @@ class JsDuckRunner 
    ]

  end



  # Copy over the images that SDK documentation links to

  def copy_sdk_images

    system "cp -r #{@sdk_dir}/extjs/docs/resources #{@out_dir}/doc-resources"

    system "cp -r #{@sdk_dir}/platform/docs/resources/* #{@out_dir}/doc-resources"

  end



  # Copy over the images that Ext4 documentation links to

  def copy_ext4_images

    system "cp -r #{@ext_dir}/docs/doc-resources #{@out_dir}/doc-resources"

  end



  # Copy over the images that Sencha Touch documentation links to.

  def copy_touch_images

    system "cp -r #{@sdk_dir}/touch/doc-resources #{@out_dir}/doc-resources"

  end



  # Copy over the images that Sencha Touch documentation links to.

  def copy_touch2_images

    system "cp -r #{@sdk_dir}/touch/docs/resources #{@out_dir}/doc-resources"

  end



  # Copy over the images that Animator documentation links to.

  def copy_animator_images

    system "cp -r #{@animator_dir}/docs/resources #{@out_dir}/doc-resources"

  end



  # Copy over SDK examples

  def copy_sdk_examples

    system "mkdir #{@out_dir}/extjs/builds"
@@ -406,8 +385,6 @@ task :sdk, [:mode] => :sass do |t, args| 
  runner.add_google_analytics if mode == "live"

  runner.run



  runner.copy_sdk_images



  runner.copy_sdk_examples if mode == "export" || mode == "live"

end
@@ -424,8 +401,6 @@ task :ext4, [:mode] => :sass do |t, args| 
  runner.add_debug if mode == "debug"

  runner.add_seo

  runner.run



  runner.copy_ext4_images

end



desc "Run JSDuck on Sencha Touch (for internal use at Sencha)\n" +
@@ -441,8 +416,6 @@ task :touch, [:mode] => :sass do |t, args| 
  runner.add_debug if mode == "debug"

  runner.add_seo if mode == "debug" || mode == "live"

  runner.run



  runner.copy_touch_images

end



desc "Run JSDuck on Sencha Touch 2 (for internal use at Sencha)\n" +
@@ -458,8 +431,6 @@ task :touch2, [:mode] => :sass do |t, args| 
  runner.add_debug if mode == "debug"

  runner.add_seo if mode == "debug" || mode == "live"

  runner.run



  runner.copy_touch2_images

end



desc "Run JSDuck on Sencha Animator (for internal use at Sencha)\n" +
@@ -477,7 +448,6 @@ task :animator, [:mode] => :sass do |t, args| 
  runner.add_seo if mode == "debug" || mode == "live"

  runner.run



  runner.copy_animator_images

  runner.copy_animator_examples

end

lib/jsduck/app.rb

+15 −6
Original line number Diff line number Diff line
@@ -19,6 +19,7 @@ require 'jsduck/guides' 
require 'jsduck/videos'

require 'jsduck/examples'

require 'jsduck/categories'

require 'jsduck/images'

require 'jsduck/json_duck'

require 'jsduck/lint'

require 'fileutils'
@@ -49,6 +50,8 @@ module JsDuck 
      Aliases.new(@relations).resolve_all

      Lint.new(@relations).run



      @images = Images.new(@opts.images)



      @welcome = Welcome.new

      if @opts.welcome

        @timer.time(:parsing) { @welcome.parse(@opts.welcome) }
@@ -103,6 +106,7 @@ module JsDuck 
        @timer.time(:generating) { @guides.write(@opts.output_dir+"/guides") }

        @timer.time(:generating) { @videos.write(@opts.output_dir+"/videos") }

        @timer.time(:generating) { @examples.write(@opts.output_dir+"/examples") }

        @timer.time(:generating) { @images.copy(@opts.output_dir+"/images") }

      end



      @timer.report
@@ -150,16 +154,21 @@ module JsDuck 


    # Formats each class

    def format_classes

      formatter = ClassFormatter.new(@relations, get_doc_formatter)

      doc_formatter = get_doc_formatter

      class_formatter = ClassFormatter.new(@relations, doc_formatter)

      # Don't format types when exporting

      formatter.include_types = !@opts.export

      class_formatter.include_types = !@opts.export

      # Format all doc-objects in parallel

      formatted_docs = @parallel.map(@relations.classes) do |cls|

        formatter.format(cls.internal_doc)

      formatted_classes = @parallel.map(@relations.classes) do |cls|

        {

          :doc => class_formatter.format(cls.internal_doc),

          :images => doc_formatter.images

        }

      end

      # Then merge the data back to classes sequentially

      formatted_docs.each do |doc|

        @relations[doc[:name]].internal_doc = doc

      formatted_classes.each do |cls|

        @relations[cls[:doc][:name]].internal_doc = cls[:doc]

        cls[:images].each {|img| @images.add(img) }

      end

    end

lib/jsduck/doc_formatter.rb

+6 −1
Original line number Diff line number Diff line
@@ -33,6 +33,9 @@ module JsDuck 
    # passed in a filename

    attr_accessor :get_example



    # This will hold list of all image paths gathered from {@img} tags.

    attr_accessor :images



    # Sets up instance to work in context of particular class, so

    # that when {@link #blah} is encountered it knows that

    # Context#blah is meant.
@@ -57,6 +60,7 @@ module JsDuck 
      @doc_context = {}

      @max_length = 120

      @relations = {}

      @images = []

      @link_tpl = '<a href="%c%#%m">%a</a>'

      @img_tpl = '<img src="%u" alt="%a"/>'

      @example_tpl = '<pre class="inline-example"><code>%a</code></pre>'
@@ -167,10 +171,11 @@ module JsDuck 


    # applies the image template

    def img(url, alt_text)

      @images << url

      @img_tpl.gsub(/(%\w)/) do

        case $1

        when '%u'

          url

          "images/" + url

        when '%a'

          CGI.escapeHTML(alt_text||"")

        else

lib/jsduck/images.rb

0 → 100644
+46 −0
Original line number Diff line number Diff line 
require "jsduck/logger"

require "fileutils"



module JsDuck



  # Looks up images from directories specified through --images option.

  class Images

    def initialize(paths)

      @paths = paths

      @images = {}

    end



    # Adds relative image path of an image

    def add(filename)

      unless @images[filename]

        @images[filename] = true

      end

    end



    # Copys over images to given output dir

    def copy(output_dir)

      @images.each_key do |img|

        unless copy_img(img, output_dir)

          Logger.instance.warn("Image #{img} not found")

        end

      end

    end



    # Attempts to copy one image, returns true on success

    def copy_img(img, output_dir)

      @paths.each do |path|

        filename = path + "/" + img

        if File.exists?(filename)

          dest = output_dir + "/" + img

          FileUtils.makedirs(File.dirname(dest))

          FileUtils.cp(filename, dest)

          Logger.instance.log("Copy #{filename} to #{dest} ...")

          return true

        end

      end

      return false

    end



  end



end

lib/jsduck/options.rb

+10 −1
Original line number Diff line number Diff line
@@ -26,6 +26,7 @@ module JsDuck 
    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
@@ -87,10 +88,11 @@ module JsDuck 
      @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
@@ -218,6 +220,13 @@ module JsDuck 
          @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 << path

        end



        opts.on('--link=TPL',

          "HTML template for replacing {@link}.",

          "Possible placeholders:",