jsduck 3.0.pre3 → 3.0

data/README.md

@@ -1,7 +1,7 @@
 JsDuck
 ======
 
-API documentation generator for Ext JS 4.
+API documentation generator for Sencha JavaScript frameworks.
 
            ,~~.
           (  6 )-_,
@@ -11,8 +11,9 @@ API documentation generator for Ext JS 4.
     ~'`~'`~'`~'`~
 
 JsDuck aims to be a better documentation generator for [Ext JS][] than
-the old [ext-doc][] was. It is used by Sencha to generate the official
-[Ext JS 4 documentation][ext4-docs].
+the old [ext-doc][] was. It is used by Sencha to document [Ext JS
+4][ext4-docs], [Sencha Touch][touch] and [several other][other-docs]
+products.
 
 The highlights of JSDuck are [Markdown][] support and keeping you DRY
 by inferring a lot of information from code.  Read the [Guide][] for
@@ -22,17 +23,17 @@ full overview.
 [ext-doc]: http://ext-doc.org/
 [Markdown]: http://daringfireball.net/projects/markdown/
 [ext4-docs]: http://docs.sencha.com/ext-js/4-0/
+[touch2-docs]: http://docs.sencha.com/touch/2-0/
+[other-docs]: http://docs.sencha.com/ext-js/4-0/
 [Guide]: https://github.com/senchalabs/jsduck/wiki/Guide
 
 
 Getting it
 ----------
 
-Standard rubygems install should do (use the `--pre` switch to get the
-latest 3.0 version which this README documents, otherwise you will get
-the stable but quite old [0.6][v0.6] version):
+Standard rubygems install should do:
 
-    $ [sudo] gem install --pre jsduck
+    $ [sudo] gem install jsduck
 
 If you encounter errors during gem installation, you may need to
 install the header files for compiling extension modules for ruby 1.8.
@@ -43,7 +44,6 @@ For **Windows** users out there, you can download the binary version,
 which includes Ruby interpreter and all dependencies bundled in a
 single .exe file.  Grab it from the [download page][].
 
-[v0.6]: https://github.com/senchalabs/jsduck/tree/v0.6
 [download page]: https://github.com/senchalabs/jsduck/downloads
 
 Usage
@@ -59,44 +59,34 @@ You can also use `--verbose` option to see what's actually happening.
 
 To generate docs for Ext JS 4 add path to the corresponding src/ dir:
 
-    $ jsduck --builtin-classes --output your/docs  extjs-4.0.2a/src
+    $ jsduck ext-4.0.7/src \
+             --builtin-classes \
+             --images ext-4.0.7/docs/images \
+             --output your/docs
 
-Running JSDuck with the current ext-4.0.2a release is expected to
-generate a lot of warnings.  Because of the bugs in doc-comments a
-global class will also get created.  You can disable this by adding
-`--ignore-global` switch.  If you are bothered by the excessive amount
-of warnings, use the `--no-warnings` switch.  For full list of command
-line options type `jsduck --help=full`.
-
-The latest ext-4.0.6 release will produce only few warnings, so use
-that if you can get it.
+The `--images` option specifies a path for images included with
+`{@img}` tags inside the source code.
 
-Finally, to get more similar result to the [official Ext JS 4
-documentation][official], copy over the doc-resources directory, which
-contains the images referenced by the documentation:
+To generate docs for your own project, simply name additional input
+directories:
 
-    $ cp -r ext-4.0.2a/docs/doc-resources your/docs/doc-resources
+    $ jsduck ext-4.0.7/src project1/js project2/js ...
 
 Note that the resulting documentation will only contain the API
 documentation.  Guides, videos and examples will not be present.
-These can be added using more command line options, but for now those
-aren't well documented as the ext-4.0.2a release doesn't contain the
-source files for these.
-
-To generate docs for your own project, simply add as many other input
-directories as needed:
-
-    $ jsduck --builtin-classes ext-4.0.2a/src project1/js project2/js --output your/docs
-
-Of course you don't have to include the whole Ext JS into your
-documentation, but if your project is built on top of it, it makes
-sense to do so - otherwise you won't be able to see which methods your
-classes inherit from Ext JS classes.
-
-To create guides, videos and other sections, read about the
-[Advanced Usage][adv] in wiki.
+These can be added using more command line options as explained in the
+[Advanced Usage][adv] section of wiki.
+
+Running JSDuck against older Ext JS than 4.0.7 is expected to generate
+a lot of warnings.  Similarly your own .js files will probably
+generate warnings too.  Sorry for that, JSDuck just wants to be
+helpful.  If you are overwhelmed by the warnings, you can disable them
+using `--no-warnings` switch.  Another thing that often happens is
+that JSDuck is unable to determine into which class a member belongs
+and will place all such items into a global class - you can disable
+this using the `--ignore-global` switch.  For full list of command
+line options type `jsduck --help=full`.
 
-[official]: http://docs.sencha.com/ext-js/4-0/
 [adv]: https://github.com/senchalabs/jsduck/wiki/Advanced-Usage
 
 
@@ -125,7 +115,10 @@ Thanks to [Ondřej Jirman](https://github.com/megous),
 [Thomas Aylott](https://github.com/subtleGradient),
 [johnnywengluu](https://github.com/johnnywengluu),
 [gevik](https://github.com/gevik),
-[ligaard](https://github.com/ligaard), and many-many others who
+[ligaard](https://github.com/ligaard),
+[Bill Hubbard](http://www.sencha.com/forum/member.php?272458-BillHubbard),
+[Ed Spencer](https://github.com/edspencer),
+[atian25](https://github.com/atian25) and many-many others who
 reported bugs, submitted patches, and provided a lot of useful input.
 
 

data/Rakefile

@@ -22,7 +22,7 @@ def load_sdk_vars
     puts "For example:"
     puts
     puts "    # path to Ext JS 4 build"
-    puts "    EXT_DIR='/path/to/ext-4.0.6'"
+    puts "    EXT_DIR='/path/to/ext-4.0.7'"
     puts "    # where to output the docs"
     puts "    OUT_DIR='/path/to/ouput/dir'"
     puts "    # path to SDK (for developers at Sencha)"
@@ -154,21 +154,47 @@ class JsDuckRunner
     @options += options
   end
 
-  def add_sdk
+  def add_sdk(mode = nil)
+
     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
 
+    if mode == 'export'
+
+      relative_sdk_path = "../"
+
+      ["template-min/extIframe.html", "template-min/welcome.html"].each do |file|
+        html = IO.read(file);
+
+        out = []
+
+        html.each_line do |line|
+          out << line.sub(/((src|href)="extjs\/)/, '\2="' + relative_sdk_path)
+        end
+
+        File.open(file, 'w') {|f| f.write(out) }
+      end
+
+      head_html = <<-EOHTML
+        <script type="text/javascript">
+          Docs.exampleBaseUrl = "#{relative_sdk_path}examples/";
+        </script>
+      EOHTML
+
+    end
+
     @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}",
+      "--footer", "Ext JS 4.0.7 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> rev #{revision}",
       "--welcome", "template/welcome.html",
       "--guides", "#{@sdk_dir}/extjs/docs/guides.json",
       "--videos", "#{@sdk_dir}/extjs/docs/videos.json",
       "--examples", "#{@sdk_dir}/extjs/examples/examples.json",
       "--categories", "#{@sdk_dir}/extjs/docs/categories.json",
+      "--local-storage-db", "ext-4",
       "--output", "#{@out_dir}",
       "--builtin-classes",
       "--images", "#{@sdk_dir}/extjs/docs/resources",
@@ -185,6 +211,7 @@ class JsDuckRunner
       "--footer", "Ext JS 3.4 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> revison #{revision}",
       "--categories", "#{@sdk_dir}/../ext-3.4.0/src/categories.json",
       "--ignore-global",
+      "--local-storage-db", "ext-3",
       "--output", "#{@out_dir}",
       "#{@sdk_dir}/../ext-3.4.0/src/core",
       "#{@sdk_dir}/../ext-3.4.0/src/data",
@@ -204,6 +231,7 @@ class JsDuckRunner
       "--ignore-global",
       "--no-warnings",
       "--images", "#{@ext_dir}/docs/doc-resources",
+      "--local-storage-db", "ext-4",
       "--output", "#{@out_dir}",
       "#{@ext_dir}/src",
     ]
@@ -221,6 +249,7 @@ class JsDuckRunner
       "--footer", "Sencha Touch 1.1 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",
+      "--local-storage-db", "touch-1",
       "--output", "#{@out_dir}",
       "--external=google.maps.Map,google.maps.LatLng",
       "--images", "#{@sdk_dir}/touch/doc-resources",
@@ -246,10 +275,12 @@ class JsDuckRunner
       "--guides", "#{@sdk_dir}/touch/docs/guides.json",
       "--examples", "#{@sdk_dir}/touch/docs/examples.json",
       "--touch-examples-ui",
+      "--local-storage-db", "touch-2",
       "--output", "#{@out_dir}",
       "--external=google.maps.Map,google.maps.LatLng",
       "--builtin-classes",
       "--img", "<p class='screenshot'><img src='%u' alt='%a'><span>%a</span></p>",
+      "--eg-iframe", "template/touch-iframe.html",
       "#{@sdk_dir}/touch/resources/themes/stylesheets/sencha-touch/default",
     ]
 
@@ -320,12 +351,33 @@ class JsDuckRunner
       "--categories", "#{@sdk_dir}/charts/docs/categories.json",
       "--guides", "#{@sdk_dir}/charts/docs/guides.json",
       "--images", "#{@sdk_dir}/charts/docs/resources",
+      "--local-storage-db", "touch-charts",
       "--output", "#{@out_dir}"
     ]
 
     @options += extract_jsb_build_files("#{@sdk_dir}/charts/touch-charts.jsb3")
   end
 
+  def add_sencha_io
+    head_html = <<-EOHTML
+      <link rel="canonical" href="http://docs.sencha.com/sencha-io/1-0/" />
+      <meta name="description" content="Sencha.io 1.0 API Documentation. Documentation on how to use the Sencha.io SDK" />
+    EOHTML
+
+    @options += [
+      "--title", "Sencha Docs - IO 1.0",
+      "--head-html", head_html,
+      "--footer", "Sencha.io 1.0 Docs - Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a>",
+      "--guides", "#{@sdk_dir}/../sync/docs/guides.json",
+      "--images", "#{@sdk_dir}/../sync/docs/resources",
+      "--local-storage-db", "sencha-io",
+      "--ignore-global",
+      "--output", "#{@out_dir}"
+    ]
+
+    @options += extract_jsb_build_files("#{@sdk_dir}/../sync/sencha-io.jsb3")
+  end
+
   def add_animator
     head_html = <<-EOHTML
       <link rel="canonical" href="http://docs.sencha.com/animator/1-0/" />
@@ -339,6 +391,7 @@ class JsDuckRunner
       # "--videos", "#{@animator_dir}/docs/videos.json",
       "--guides", "#{@animator_dir}/docs/guides.json",
       # "--examples", "#{@animator_dir}/docs/examples/examples.json",
+      "--local-storage-db", "animator",
       "--output", "#{@out_dir}",
     ]
   end
@@ -515,7 +568,7 @@ task :sdk, [:mode] => :sass do |t, args|
   compress if mode == "export" || mode == "live"
 
   runner = JsDuckRunner.new
-  runner.add_sdk
+  runner.add_sdk(mode)
   runner.add_debug if mode == "debug"
   runner.add_seo if mode == "debug" || mode == "live"
   runner.add_sdk_export_notice if mode == "export"
@@ -611,6 +664,23 @@ task :charts, [:mode] => :sass do |t, args|
   runner.run
 end
 
+desc "Run JSDuck on Sencha.IO Sync (for internal use at Sencha)\n" +
+     "senchaio         - creates debug/development version\n" +
+     "senchaio[export] - create live version for deployment\n"
+     "senchaio[live]   - create live version for deployment\n"
+task :senchaio, [:mode] => :sass do |t, args|
+  mode = args[:mode] || "debug"
+  throw "Unknown mode #{mode}" unless ["debug", "export", "live"].include?(mode)
+  compress if mode == "live"
+
+  runner = JsDuckRunner.new
+  runner.add_sencha_io
+  runner.add_debug if mode == "debug"
+  runner.add_seo if mode == "debug" || mode == "live"
+  runner.add_google_analytics if mode == "live"
+  runner.run
+end
+
 desc "Run JSDuck JSON Export (for internal use at Sencha)\n" +
      "export[touch]  - creates export for Touch 1\n" +
      "export[touch2] - creates export for Touch 2"

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.7"
 
   s.name = 'jsduck'
-  s.version = '3.0.pre3'
-  s.date = '2011-10-17'
+  s.version = '3.0'
+  s.date = '2011-10-21'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/app.rb

@@ -73,7 +73,8 @@ module JsDuck
       @categories = Categories.new(get_doc_formatter, @relations)
       if @opts.categories_path
         @categories.parse(@opts.categories_path)
-        @categories.validate
+      else
+        @categories.auto_generate
       end
 
       clear_output_dir unless @opts.export == :stdout
@@ -95,6 +96,9 @@ module JsDuck
           FileUtils.rm(@opts.output_dir+"/index.php")
           FileUtils.cp(@opts.output_dir+"/template.html", @opts.output_dir+"/index.html")
         end
+        if @opts.eg_iframe
+          FileUtils.cp(@opts.eg_iframe, @opts.output_dir+"/eg-iframe.html")
+        end
         write_src(parsed_files)
         format_classes
         write_app_data

data/lib/jsduck/auto_categories.rb

@@ -0,0 +1,80 @@
+module JsDuck
+
+  # Automatically divides all available classes into categories
+  class AutoCategories
+    def initialize(relations)
+      @relations = relations
+    end
+
+    # Performs the generation
+    def generate
+      # list names of all public classes
+      class_names = @relations.to_a.find_all {|cls| !cls[:private] }.map {|cls| cls[:name] }
+
+      # divide classes into top-level categories by namespace
+      categories = categorize(class_names)
+
+      # in each category, create sub-categories
+      categories.each_pair do |ns, classes|
+        categories[ns] = categorize(classes, 1)
+      end
+
+      # Turn categories hash into array, sort everything
+      categories_array = []
+      categories.each_pair do |ns, groups|
+        groups_array = []
+        groups.each_pair do |gns, classes|
+          groups_array << {
+            "name" => gns,
+            "classes" => classes.sort
+          }
+        end
+        groups_array.sort! {|a, b| cat_compare(a, b) }
+        categories_array << {
+          "name" => ns,
+          "groups" => groups_array
+        }
+      end
+      categories_array.sort! {|a, b| cat_compare(a, b) }
+
+      return categories_array
+    end
+
+    # Divides classes into categories by namespace.  Collapses
+    # categories having only one class into a category "Others..."
+    def categorize(class_names, level=0)
+      categories = {}
+      class_names.each do |name|
+        ns = name.split(/\./)[level] || name.split(/\./)[0]
+        categories[ns] = [] unless categories[ns]
+        categories[ns] << name
+      end
+
+      globals = []
+      categories.each_pair do |ns, classes|
+        if classes.length == 1
+          globals << classes[0]
+          categories.delete(ns)
+        end
+      end
+      if globals.length > 0
+        categories["Others..."] = globals
+      end
+
+      categories
+    end
+
+    # Comparison function for sorting categories that always places
+    # "Others..." category at the end.
+    def cat_compare(a, b)
+      if a["name"] == "Others..."
+        1
+      elsif b["name"] == "Others..."
+        -1
+      else
+        a["name"] <=> b["name"]
+      end
+    end
+  end
+
+end

data/lib/jsduck/categories.rb

@@ -1,5 +1,6 @@
 require 'jsduck/logger'
 require 'jsduck/json_duck'
+require 'jsduck/auto_categories'
 
 module JsDuck
 
@@ -11,6 +12,11 @@ module JsDuck
       @categories = []
     end
 
+    # Automatically divides all available classes into categories
+    def auto_generate
+      @categories = AutoCategories.new(@relations).generate
+    end
+
     # Parses categories in JSON file
     def parse(path)
       @categories = JsonDuck.read(path)
@@ -29,6 +35,8 @@ module JsDuck
           end.flatten
         end
       end
+
+      validate
     end
 
     # Expands class name like 'Foo.*' into multiple class names.

data/lib/jsduck/lexer.rb

@@ -127,12 +127,12 @@ module JsDuck
         elsif @input.check(/'/)
           return {
             :type => :string,
-            :value => @input.scan(/'([^'\\]|\\.)*'/m).sub(/^'(.*)'$/m, "\\1")
+            :value => @input.scan(/'([^'\\]|\\.)*('|\Z)/m).gsub(/\A'|'\Z/m, "")
           }
         elsif @input.check(/"/)
           return {
             :type => :string,
-            :value => @input.scan(/"([^"\\]|\\.)*"/m).sub(/^"(.*)"$/m, "\\1")
+            :value => @input.scan(/"([^"\\]|\\.)*("|\Z)/m).gsub(/\A"|"\Z/m, "")
           }
         elsif @input.check(/\//)
           # Several things begin with dash:
@@ -153,7 +153,7 @@ module JsDuck
           elsif regex?
             return {
               :type => :regex,
-              :value => @input.scan(/\/([^\/\\]|\\.)*\/[gim]*/)
+              :value => @input.scan(META_REGEX)
             }
           else
             return {
@@ -202,6 +202,20 @@ module JsDuck
       @input.scan(/\s+/)
     end
 
+    # A regex to match a regex
+    META_REGEX = %r{
+      /               (?# beginning    )
+      (
+        [^/\[\\]      (?# any character except \ / [    )
+        |
+        \\.           (?# an escaping \ followed by any character    )
+        |
+        \[ ([^\]\\]|\\.)* \]    (?# [...] containing any characters including /    )
+                                (?# except \ ] which have to be escaped    )
+      )*
+      (/[gim]*|\Z)   (?# ending + modifiers    )
+    }x
+
     KEYWORDS = {
       "break" => true,
       "case" => true,