From 003241df82a4c90013b8608d5876b34db0c6a1ae Mon Sep 17 00:00:00 2001 From: Rene Saarsoo Date: Tue, 27 Sep 2011 19:35:26 +0300 Subject: [PATCH] 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. --- Rakefile | 40 ++++---------------------------- lib/jsduck/app.rb | 21 ++++++++++++----- lib/jsduck/doc_formatter.rb | 7 +++++- lib/jsduck/images.rb | 46 +++++++++++++++++++++++++++++++++++++ lib/jsduck/options.rb | 11 ++++++++- 5 files changed, 82 insertions(+), 43 deletions(-) create mode 100644 lib/jsduck/images.rb diff --git a/Rakefile b/Rakefile index 1ca58079..28d30e99 100644 --- a/Rakefile +++ b/Rakefile @@ -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 JSDuck 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 diff --git a/lib/jsduck/app.rb b/lib/jsduck/app.rb index cc719677..5532e82d 100644 --- a/lib/jsduck/app.rb +++ b/lib/jsduck/app.rb @@ -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 diff --git a/lib/jsduck/doc_formatter.rb b/lib/jsduck/doc_formatter.rb index d14841ae..fac8831f 100644 --- a/lib/jsduck/doc_formatter.rb +++ b/lib/jsduck/doc_formatter.rb @@ -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' @img_tpl = '%a' @example_tpl = '
%a
' @@ -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 diff --git a/lib/jsduck/images.rb b/lib/jsduck/images.rb new file mode 100644 index 00000000..a17bd760 --- /dev/null +++ b/lib/jsduck/images.rb @@ -0,0 +1,46 @@ +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 diff --git a/lib/jsduck/options.rb b/lib/jsduck/options.rb index 264a14d0..6f953afa 100644 --- a/lib/jsduck/options.rb +++ b/lib/jsduck/options.rb @@ -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' # Note that we wrap image template inside

because {@img} often # appears inline within text, but that just looks ugly in HTML - @img_tpl = '

%a

' + @img_tpl = '

%a

' @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:", -- GitLab