jsduck 2.0.pre4 → 3.0.pre

data/Rakefile

@@ -10,16 +10,6 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = "spec/**/*_spec.rb"
 end
 
-desc "Build gem locally"
-task :build do
-  system "gem build jsduck.gemspec"
-end
-
-desc "Install gem locally"
-task :install => :build do
-  system "gem install --user-install jsduck"
-end
-
 def load_sdk_vars
   if File.exists?("sdk-vars.rb")
     require "sdk-vars.rb"
@@ -30,128 +20,366 @@ def load_sdk_vars
     puts
     puts "For example:"
     puts
-    puts "    SDK_DIR='/path/to/SDK'"
+    puts "    # path to Ext JS 4 build"
+    puts "    EXT_DIR='/path/to/ext-4.0.6'"
+    puts "    # where to output the docs"
     puts "    OUT_DIR='/path/to/ouput/dir'"
-    puts "    EXT_DIR='/path/to/ext/dir'"
+    puts "    # path to SDK (for developers at Sencha)"
+    puts "    SDK_DIR='/path/to/SDK'"
     exit 1
   end
 end
 
-def run_jsduck(extra_options)
-  # Pass multiple arguments to system, so we'll take advantage of the built-in escaping
-  system(*[
-    "ruby", "bin/jsduck",
-    # --external=Error to ignore the Error class that Ext.Error extends.
-    "--external", "Error",
-    "--guides", "#{SDK_DIR}/guides",
-    "--guides-order", "getting,class,application,layouts,data,grid,tree,drawing,forms,components,theming,direct",
-    "--categories", "#{SDK_DIR}/extjs/doc-resources/categories.json",
-    "--output", "#{OUT_DIR}",
-  ].concat(extra_options))
-
-  # Finally copy over the images that documentation links to.
-  system "cp -r #{SDK_DIR}/extjs/doc-resources #{OUT_DIR}/doc-resources"
-  system "cp -r #{SDK_DIR}/platform/doc-resources/* #{OUT_DIR}/doc-resources"
+# Compress JS/CSS file in-place
+# Using a hackish way to access yui-compressor
+def yui_compress(fname)
+  system "java -jar $(dirname $(which sencha))/../jsbuilder/ycompressor/ycompressor.jar -o #{fname} #{fname}"
 end
 
-desc "Run JSDuck on ExtJS SDK"
-task :sdk do
-  load_sdk_vars
-  run_jsduck([
-    "--extjs-path", "extjs/ext-debug.js",
-    # to create symbolic links to template files instead of copying them over.
-    # Useful for development.  Turn off for deployment.
-    "--template-links",
-    "#{SDK_DIR}/extjs/src",
-    "#{SDK_DIR}/platform/src",
-    "#{SDK_DIR}/platform/core/src",
-  ])
+# Reads in all CSS files referenced between BEGIN CSS and END CSS markers.
+# Deletes those input CSS files and writes out concatenated CSS to
+# resources/css/app.css
+# Finally replaces the CSS section with <link> to that one CSS file.
+def combine_css(html, dir, opts = :write)
+  css_section_re = /<!-- BEGIN CSS -->.*<!-- END CSS -->/m
+  css = []
+  css_section_re.match(html)[0].each_line do |line|
+    if line =~ /<link rel="stylesheet" href="(.*?)"/
+      file = $1
+      css << IO.read(dir + "/" + file)
+      system("rm", dir + "/" + file) if opts == :write
+    end
+  end
+
+  if opts == :write
+    fname = "#{dir}/resources/css/app.css"
+    File.open(fname, 'w') {|f| f.write(css.join("\n")) }
+    yui_compress(fname)
+  end
+  html.sub(css_section_re, '<link rel="stylesheet" href="resources/css/app.css" type="text/css" />')
 end
 
-def run_jsduck_export(extra_options, ext_dir)
-  load_sdk_vars
-  rev = `git rev-parse HEAD`.slice(0, 7)
-  head_html = <<-EOHTML
-    <link rel="canonical" href="http://docs.sencha.com/ext-js/4-0/" />
-    <meta name="description" content="Ext JS 4.0 API Documentation from Sencha. Class documentation, Guides and Videos on how to create Javascript applications with Ext JS 4">
-  EOHTML
-
-  run_jsduck([
-    "--title", "Ext JS 4.0.2a API Documentation",
-    "--footer", "ExtJS 4.0.2a Documentation from Sencha. Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{rev}",
-    "--head-html", head_html,
-    "#{SDK_DIR}/extjs/src",
-    "#{SDK_DIR}/platform/src",
-    "#{SDK_DIR}/platform/core/src",
-  ].concat(extra_options))
-
-  system "rm #{OUT_DIR}/extjs"
-  system "mkdir -p #{OUT_DIR}/extjs/resources/themes/images"
-  system "cp #{EXT_DIR}/ext-all.js #{OUT_DIR}/extjs"
-  system "cp -r #{ext_dir}/resources/themes/images/default #{OUT_DIR}/extjs/resources/themes/images"
-  system "rm -rf #{ext_dir}/resources/sass"
-  system "rm -rf #{OUT_DIR}/resources/.sass-cache"
+# Same thing for JavaScript, result is written to: app.js
+def combine_js(html, dir)
+  js_section_re = /<!-- BEGIN JS -->.*<!-- END JS -->/m
+  js = []
+  js_section_re.match(html)[0].each_line do |line|
+    if line =~ /<script .* src="(.*)">/
+      file = $1
+      js << IO.read(dir + "/" + file)
+      if file !~ /ext\.js/
+        system("rm", dir + "/" + file)
+      end
+    elsif line =~ /<script .*>(.*)<\/script>/
+      js << $1
+    end
+  end
+
+  fname = "#{dir}/app.js"
+  File.open(fname, 'w') {|f| f.write(js.join("\n")) }
+  yui_compress(fname)
+  html.sub(js_section_re, '<script type="text/javascript" src="app.js"></script>')
 end
 
-desc "Run JSDuck on ExtJS SDK to create release version of docs app"
-task :export do
+# Compress JavaScript and CSS files of JSDuck
+def compress
   load_sdk_vars
-  run_jsduck_export([
-    "--body-html", <<-EOHTML
-    <div id="notice-text" style="display: none">
-      Use <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a> for up to date documentation and features
-    </div>
+
+  # Clean up template-min/ left over from previous compress task
+  system("rm", "-rf", "template-min")
+  # Copy template/ files to template-min/
+  system("cp", "-r", "template", "template-min")
+  # Now do everything that follows in template-min/ dir
+  dir = "template-min"
+
+  # Create JSB3 file for Docs app
+  system("sencha", "create", "jsb", "-a", "#{dir}/build-js.html", "-p", "#{dir}/app.jsb3")
+  # Concatenate files listed in JSB3 file
+  system("sencha", "build", "-p", "#{dir}/app.jsb3", "-d", dir)
+  # Remove intermediate build files
+  system("rm", "#{dir}/app.jsb3")
+  system("rm", "#{dir}/all-classes.js")
+  # Replace app.js with app-all.js
+  system("mv", "#{dir}/app-all.js", "#{dir}/app.js")
+  # Remove the entire app/ dir
+  system("rm", "-r", "#{dir}/app")
+
+  # Concatenate CSS in print-template.html file
+  print_template = "#{dir}/print-template.html";
+  html = IO.read(print_template);
+  # Just modify HTML to link app.css, don't write files.
+  html = combine_css(html, dir, :replace_html_only)
+  File.open(print_template, 'w') {|f| f.write(html) }
+
+  # Concatenate CSS and JS files referenced in template.html file
+  template_html = "#{dir}/template.html"
+  html = IO.read(template_html)
+  html = combine_css(html, dir)
+  html = combine_js(html, dir)
+  File.open(template_html, 'w') {|f| f.write(html) }
+
+  # Clean up SASS files
+  # (But keep prettify lib, which is needed for source files)
+  system "rm -rf #{dir}/resources/sass"
+  system "rm -rf #{dir}/resources/codemirror"
+  system "rm -rf #{dir}/resources/.sass-cache"
+
+  # Empty the extjs dir, leave only the main JS files, CSS and images
+  system "rm -rf #{dir}/extjs"
+  system "mkdir #{dir}/extjs"
+  system "cp #{EXT_DIR}/ext-all.js #{dir}/extjs"
+  system "cp #{EXT_DIR}/ext-all-debug.js #{dir}/extjs"
+  system "cp #{EXT_DIR}/bootstrap.js #{dir}/extjs"
+  system "mkdir -p #{dir}/extjs/resources/css"
+  system "cp #{EXT_DIR}/resources/css/ext-all.css #{dir}/extjs/resources/css"
+  system "mkdir -p #{dir}/extjs/resources/themes/images"
+  system "cp -r #{EXT_DIR}/resources/themes/images/default #{dir}/extjs/resources/themes/images"
+end
+
+
+class JsDuckRunner
+  def initialize
+    @options = []
+    load_sdk_vars
+    @sdk_dir = SDK_DIR
+    @out_dir = OUT_DIR
+    @ext_dir = EXT_DIR
+  end
+
+  def add_options(options)
+    @options += options
+  end
+
+  def add_sdk
+    head_html = <<-EOHTML
+      <link rel="canonical" href="http://docs.sencha.com/ext-js/4-0/" />
+      <meta name="description" content="Ext JS 4.0 API Documentation from Sencha. Class documentation, Guides and Videos on how to create Javascript applications with Ext JS 4">
+    EOHTML
+
+    @options += [
+      "--title", "Sencha Docs - Ext JS 4.0",
+      "--head-html", head_html,
+      "--footer", "Ext JS 4.0.6 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> rev #{revision}",
+      "--welcome", "template/welcome.html",
+      "--guides", "#{@sdk_dir}/guides/guides.json",
+      "--videos", "#{@sdk_dir}/guides/videos.json",
+      "--examples", "#{@sdk_dir}/extjs/examples/examples.json",
+      "--inline-examples", "#{@sdk_dir}/extjs/doc-resources",
+      "--categories", "#{@sdk_dir}/extjs/doc-resources/categories.json",
+      "--output", "#{@out_dir}",
+      "#{@sdk_dir}/extjs/src",
+      "#{@sdk_dir}/platform/src",
+      "#{@sdk_dir}/platform/core/src",
+    ]
+  end
+
+  def add_ext4
+    @options += [
+      "--title", "Sencha Docs - Ext JS 4.0",
+      "--footer", "Ext JS 4.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
+      "--ignore-global",
+      "--no-warnings",
+      "--output", "#{@out_dir}",
+      "#{@ext_dir}/src",
+    ]
+  end
+
+  def add_touch
+    head_html = <<-EOHTML
+      <link rel="canonical" href="http://docs.sencha.com/touch/1-0/" />
+      <meta name="description" content="Sencha Touch 1.0 API Documentation from Sencha. Documentation on how to create Javascript applications with Sencha Touch">
     EOHTML
-  ], EXT_DIR)
+
+    @options += [
+      "--title", "Sencha Docs - Touch 1.0",
+      "--head-html", head_html,
+      "--footer", "Sencha Touch 1.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
+      "--categories", "#{@sdk_dir}/touch/doc-resources/categories.json",
+      "--videos", "#{@sdk_dir}/touch/doc-resources/videos.json",
+      "--output", "#{@out_dir}",
+      "#{@sdk_dir}/touch/src/core",
+      "#{@sdk_dir}/touch/src/data",
+      "#{@sdk_dir}/touch/src/gestures",
+      "#{@sdk_dir}/touch/src/layout",
+      "#{@sdk_dir}/touch/src/plugins",
+      "#{@sdk_dir}/touch/src/util",
+      "#{@sdk_dir}/touch/src/widgets",
+      "#{@sdk_dir}/touch/src/platform/src",
+      "#{@sdk_dir}/touch/resources/themes/stylesheets/sencha-touch/default",
+    ]
+  end
+
+  # Returns shortened hash of naming current git revision
+  def revision
+    `git rev-parse HEAD`.slice(0, 7)
+  end
+
+  def add_debug
+    @options += [
+      "--extjs-path", "extjs/ext-all-debug.js",
+      "--template-links",
+      "--template", "template",
+    ]
+  end
+
+  def add_seo
+    @options += [
+      "--seo",
+    ]
+  end
+
+  def add_sdk_export_notice
+    @options += [
+      "--body-html", <<-EOHTML
+      <div id="notice-text" style="display: none">
+        Use <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a> for up to date documentation and features
+      </div>
+      EOHTML
+    ]
+  end
+
+  def add_google_analytics
+    @options += [
+      "--body-html", <<-EOHTML
+      <script type="text/javascript">
+        var _gaq = _gaq || [];
+        _gaq.push(['_setAccount', 'UA-1396058-10']);
+        _gaq.push(['_trackPageview']);
+        (function() {
+          var ga = document.createElement('script');
+          ga.type = 'text/javascript';
+          ga.async = true;
+          ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+          var s = document.getElementsByTagName('script')[0];
+          s.parentNode.insertBefore(ga, s);
+        })();
+
+        Docs.initEventTracking = function() {
+            Docs.App.getController('Classes').addListener({
+                showClass: function(cls) {
+                    _gaq.push(['_trackEvent', 'Classes', 'Show', cls]);
+                },
+                showMember: function(cls, anchor) {
+                    _gaq.push(['_trackEvent', 'Classes', 'Member', cls + ' - ' + anchor]);
+                }
+            });
+            Docs.App.getController('Guides').addListener({
+                showGuide: function(guide) {
+                    _gaq.push(['_trackEvent', 'Guides', 'Show', guide]);
+                }
+            });
+            Docs.App.getController('Videos').addListener({
+                showVideo: function(video) {
+                    _gaq.push(['_trackEvent', 'Video', 'Show', video]);
+                }
+            });
+            Docs.App.getController('Examples').addListener({
+                showExample: function(example) {
+                    _gaq.push(['_trackEvent', 'Example', 'Show', example]);
+                }
+            });
+        }
+      </script>
+    EOHTML
+    ]
+  end
+
+  # Copy over the images that SDK documentation links to
+  def copy_sdk_images
+    system "cp -r #{@sdk_dir}/extjs/doc-resources #{@out_dir}/doc-resources"
+    system "cp -r #{@sdk_dir}/platform/doc-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 SDK examples
+  def copy_sdk_examples
+    system "mkdir #{@out_dir}/extjs/builds"
+    system "cp #{@ext_dir}/builds/ext-core.js #{@out_dir}/extjs/builds/ext-core.js"
+    system "cp #{@ext_dir}/release-notes.html #{@out_dir}/extjs"
+    system "cp -r #{@ext_dir}/examples #{@out_dir}/extjs"
+    system "cp -r #{@ext_dir}/welcome #{@out_dir}/extjs"
+  end
+
+  def run
+    # Pass multiple arguments to system, so we'll take advantage of the built-in escaping
+    system(*["ruby", "bin/jsduck"].concat(@options))
+  end
 end
 
-desc "Run JSDuck on ExtJS SDK to create live docs app"
-task :live_docs do
-  load_sdk_vars
-  run_jsduck_export([
-    "--body-html", <<-EOHTML
-    <script type="text/javascript">
-      var _gaq = _gaq || [];
-      _gaq.push(['_setAccount', 'UA-1396058-10']);
-      _gaq.push(['_trackPageview']);
-      (function() {
-        var ga = document.createElement('script');
-        ga.type = 'text/javascript';
-        ga.async = true;
-        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-        var s = document.getElementsByTagName('script')[0];
-        s.parentNode.insertBefore(ga, s);
-      })();
-
-      Docs.initEventTracking = function() {
-          Docs.App.getController('Classes').addListener({
-              showClass: function(cls) {
-                  _gaq.push(['_trackEvent', 'Classes', 'Show', cls]);
-              },
-              showMember: function(cls, anchor) {
-                  _gaq.push(['_trackEvent', 'Classes', 'Member', cls + ' - ' + anchor]);
-              },
-              showGuide: function(guide) {
-                  _gaq.push(['_trackEvent', 'Guides', 'Show', guide]);
-              }
-          });
-      }
-    </script>
-  EOHTML
-  ], "#{SDK_DIR}/extjs/build/sdk")
+# Run compass to generate CSS files
+task :sass do
+  system "compass compile --quiet template/resources/sass"
 end
 
-desc "Run JSDuck on the Docs app itself"
-task :docs do
-  load_sdk_vars
-  run_jsduck([
-    "--template-links",
-    "#{SDK_DIR}/extjs/src",
-    "#{SDK_DIR}/platform/src",
-    "#{SDK_DIR}/platform/core/src",
-    "template/app",
-    "template/app.js",
-  ])
+desc "Run JSDuck on Ext JS SDK (for internal use at Sencha)\n" +
+     "sdk         - creates debug/development version\n" +
+     "sdk[export] - creates export version\n" +
+     "sdk[live]   - create live version for deployment\n"
+task :sdk, [:mode] => :sass do |t, args|
+  mode = args[:mode] || "debug"
+  throw "Unknown mode #{mode}" unless ["debug", "export", "live"].include?(mode)
+  compress if mode == "export" || mode == "live"
+
+  runner = JsDuckRunner.new
+  runner.add_sdk
+  runner.add_debug if mode == "debug"
+  runner.add_seo if mode == "debug" || mode == "live"
+  runner.add_export_notice if mode == "export"
+  runner.add_google_analytics if mode == "live"
+  runner.run
+
+  runner.copy_sdk_images
+
+  runner.copy_sdk_examples if mode == "export" || mode == "live"
+end
+
+desc "Run JSDuck on official Ext JS 4.0.2a build\n" +
+     "ext4             - creates debug/development version\n" +
+     "ext4[export]     - creates export/deployable version\n"
+task :ext4, [:mode] => :sass do |t, args|
+  mode = args[:mode] || "debug"
+  throw "Unknown mode #{mode}" unless ["debug", "export"].include?(mode)
+  compress if mode == "export"
+
+  runner = JsDuckRunner.new
+  runner.add_ext4
+  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" +
+     "touch       - creates debug/development version\n" +
+     "touch[live] - create live version for deployment\n"
+task :touch, [:mode] => :sass do |t, args|
+  mode = args[:mode] || "debug"
+  throw "Unknown mode #{mode}" unless ["debug", "live"].include?(mode)
+  compress if mode == "live"
+
+  runner = JsDuckRunner.new
+  runner.add_touch
+  runner.add_debug if mode == "debug"
+  runner.add_seo if mode == "debug" || mode == "live"
+  runner.run
+
+  runner.copy_touch_images
+end
+
+desc "Build JSDuck gem"
+task :gem => :sass do
+  compress
+  system "gem build jsduck.gemspec"
 end
 
 task :default => :spec