Commit 8677a2c3 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Merge branch 'inline-examples'

parents c37b80d1 fd4fcb17

Rakefile

+98 −13
Original line number Diff line number Diff line
@@ -44,6 +44,7 @@ def run_jsduck(extra_options) 
    # --external=Error to ignore the Error class that Ext.Error extends.

    "--external", "Error",

    "--guides", "#{SDK_DIR}/guides",

    "--examples", "#{SDK_DIR}/extjs/doc-resources",

    "--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}",
@@ -68,7 +69,7 @@ task :sdk do 
  ])

end



def run_jsduck_export(extra_options, ext_dir)

def run_jsduck_export(extra_options)

  load_sdk_vars

  rev = `git rev-parse HEAD`.slice(0, 7)

  head_html = <<-EOHTML
@@ -85,16 +86,11 @@ def run_jsduck_export(extra_options, ext_dir) 
    "#{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"

end



desc "Run JSDuck on ExtJS SDK to create release version of docs app"

task :export do

# Use the :export task instead

desc "Base task for creating export"

task :base_export do

  load_sdk_vars

  run_jsduck_export([

    "--body-html", <<-EOHTML
@@ -102,11 +98,12 @@ task :export do 
      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

  ], EXT_DIR)

  ])

end



desc "Run JSDuck on ExtJS SDK to create live docs app"

task :live_docs do

# Use the :live_docs task instead

desc "Base task for creating live docs"

task :base_live_docs do

  load_sdk_vars

  run_jsduck_export([

    "--body-html", <<-EOHTML
@@ -138,7 +135,7 @@ task :live_docs do 
      }

    </script>

  EOHTML

  ], "#{SDK_DIR}/extjs/build/sdk")

  ])

end



desc "Run JSDuck on the Docs app itself"
@@ -154,4 +151,92 @@ task :docs do 
  ])

end



# 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



# 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, base_dir)

  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(base_dir + "/" + file)

      system("rm", base_dir + "/" + file)

    end

  end



  fname = "#{OUT_DIR}/resources/css/app.css"

  File.open(fname, 'w') {|f| f.write(css.join("\n")) }

  yui_compress(fname)

  html.sub(css_section_re, '<link rel="stylesheet" href="resources/css/app.css" type="text/css" />')

end



# Same thing for JavaScript, result is written to: app.js

def combine_js(html, base_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(base_dir + "/" + file)

      system("rm", base_dir + "/" + file)

    elsif line =~ /<script .*>(.*)<\/script>/

      js << $1

    end

  end



  fname = "#{OUT_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



# Use :export or :live_docs tasks instead of running this separately

desc "Compresses JavaScript and CSS files in output dir"

task :compress do

  load_sdk_vars

  # Create JSB3 file for Docs app

  system("sencha", "create", "jsb", "-a", "#{OUT_DIR}/index.html", "-p", "#{OUT_DIR}/app.jsb3")

  # Concatenate files listed in JSB3 file

  system("sencha", "build", "-p", "#{OUT_DIR}/app.jsb3", "-d", OUT_DIR)

  # Remove intermediate build files

  system("rm", "#{OUT_DIR}/app.jsb3")

  system("rm", "#{OUT_DIR}/all-classes.js")

  # Replace app.js with app-all.js

  system("mv", "#{OUT_DIR}/app-all.js", "#{OUT_DIR}/app.js")

  # Remove the entire app/ dir

  system("rm", "-r", "#{OUT_DIR}/app")



  # Concatenate CSS and JS files referenced in index.html file

  html = IO.read("#{OUT_DIR}/index.html")

  html = combine_css(html, OUT_DIR)

  html = combine_js(html, OUT_DIR)

  File.open("#{OUT_DIR}/index.html", 'w') {|f| f.write(html) }



  # Clean up SASS files

  system "rm -rf #{OUT_DIR}/resources/sass"

  system "rm -rf #{OUT_DIR}/resources/.sass-cache"



  # Empty the extjs dir, leave only the main JS file, CSS and images (for inline examples)

  system "rm -rf #{OUT_DIR}/extjs"

  system "mkdir -p #{OUT_DIR}/extjs/resources/css"

  system "mkdir -p #{OUT_DIR}/extjs/resources/themes/images"

  system "cp #{EXT_DIR}/ext-all-debug.js #{OUT_DIR}/extjs"

  system "cp #{EXT_DIR}/resources/css/ext-all.css #{OUT_DIR}/extjs/resources/css"

  system "cp -r #{EXT_DIR}/resources/themes/images/default #{OUT_DIR}/extjs/resources/themes/images"

end



desc "Run JSDuck on ExtJS SDK to create release version of docs app"

task :export => [:base_export, :compress]



desc "Run JSDuck on ExtJS SDK to create live docs app"

task :live_docs => [:base_live_docs, :compress]



task :default => :spec

bin/jsduck

+5 −1
Original line number Diff line number Diff line
@@ -99,6 +99,10 @@ opts = OptionParser.new do | opts | 
    app.categories_path = path

  end



  opts.on('--examples=PATH', "Path to examples directory.", " ") do |path|

    app.examples_dir = path

  end



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

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

    "Possible placeholders:",
@@ -154,7 +158,7 @@ opts = OptionParser.new do | opts | 


  opts.on('--extjs-path=PATH',

    "Path for main ExtJS JavaScript file.  Useful for specifying",

    "something different than extjs/ext-all.js", " ") do |path|

    "something different than extjs/ext.js", " ") do |path|

    app.extjs_path = path

  end

lib/jsduck/app.rb

+4 −1
Original line number Diff line number Diff line
@@ -27,6 +27,7 @@ module JsDuck 
    attr_accessor :output_dir

    attr_accessor :template_dir

    attr_accessor :guides_dir

    attr_accessor :examples_dir

    attr_accessor :guides_order

    attr_accessor :categories_path

    attr_accessor :template_links
@@ -48,6 +49,7 @@ module JsDuck 
      @output_dir = nil

      @template_dir = nil

      @guides_dir = nil

      @examples_dir = nil

      @guides_order = nil

      @categories_path = nil

      @template_links = false
@@ -61,7 +63,7 @@ module JsDuck 
      @show_private_classes = false

      @title = "Ext JS API Documentation"

      @footer = 'Generated with <a href="https://github.com/senchalabs/jsduck">JSDuck</a>.'

      @extjs_path = "extjs/ext-all.js"

      @extjs_path = "extjs/ext.js"

      @local_storage_db = "docs"

      @head_html = ""

      @body_html = ""
@@ -252,6 +254,7 @@ module JsDuck 
      formatter.link_tpl = @link_tpl if @link_tpl

      formatter.img_tpl = @img_tpl if @img_tpl

      formatter.relations = relations

      formatter.get_example = lambda {|path| IO.read(@examples_dir + "/" + path) } if @examples_dir

      formatter

    end

lib/jsduck/doc_formatter.rb

+41 −3
Original line number Diff line number Diff line
@@ -29,6 +29,10 @@ module JsDuck 
    # Default value: '<img src="%u" alt="%a"/>'

    attr_accessor :img_tpl



    # Assign to this a function that retrieves the example code when

    # passed in a filename

    attr_accessor :get_example



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

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

    # Context#blah is meant.
@@ -55,8 +59,11 @@ module JsDuck 
      @relations = {}

      @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>'

      @link_re = /\{@link\s+(\S*?)(?:\s+(.+?))?\}/m

      @img_re = /\{@img\s+(\S*?)(?:\s+(.+?))?\}/m

      @example_re = /\{@example\s+(\S*?)\s*\}/m

      @example_annotation_re = /<pre><code>@example( +[^\n]*)?\s+/m

    end



    # Replaces {@link} and {@img} tags, auto-generates links for
@@ -67,6 +74,10 @@ module JsDuck 
    #

    # Replaces {@img path/to/image.jpg Alt text} with HTML from @img_tpl.

    #

    # Replaces {@example path/to/example.js} with source from that file.

    #

    # Adds 'inline-example' class to code examples beginning with @example.

    #

    # Additionally replaces strings recognized as ClassNames with

    # links to these classes.  So one doesn even need to use the @link

    # tag to create a link.
@@ -78,10 +89,15 @@ module JsDuck 
          out += replace_link_tag(s.scan(@link_re))

        elsif s.check(@img_re)

          out += replace_img_tag(s.scan(@img_re))

        elsif s.check(/\{/)

          out += s.scan(/\{/)

        elsif s.check(@example_re)

          out += replace_example_tag(s.scan(@example_re))

        elsif s.check(@example_annotation_re)

          s.scan(@example_annotation_re)

          out += '<pre class="inline-example"><code>'

        elsif s.check(/[{<]/)

          out += s.scan(/[{<]/)

        else

          out += replace_class_names(s.scan(/[^{]+/))

          out += replace_class_names(s.scan(/[^{<]+/))

        end

      end

      out
@@ -128,6 +144,10 @@ module JsDuck 
      input.sub(@img_re) { img($1, $2) }

    end



    def replace_example_tag(input)

      input.sub(@example_re) { example($1) }

    end



    def replace_class_names(input)

      input.gsub(/(\A|\s)([A-Z][A-Za-z0-9.]*[A-Za-z0-9])(?:(#)([A-Za-z0-9]+))?([.,]?(?:\s|\Z))/m) do

        before = $1
@@ -159,6 +179,24 @@ module JsDuck 
      end

    end



    # Replaces example template with example read from file

    def example(path)

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

        case $1

        when '%a'

          if @get_example

            CGI.escapeHTML(@get_example.call(path))

          else

            file = @doc_context[:filename]

            line = @doc_context[:linenr]

            Logger.instance.warn("--examples not specified, but {@example} found in #{file} line #{line}.")

          end

        else

          $1

        end

      end

    end



    # applies the link template

    def link(cls, member, anchor_text, type=nil)

      # Use the canonical class name for link (not some alternateClassName)

lib/jsduck/source_writer.rb

+2 −2
Original line number Diff line number Diff line
@@ -51,8 +51,8 @@ module JsDuck 
<head>

  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

  <title>The source code</title>

  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />

  <script type="text/javascript" src="../prettify/prettify.js"></script>

  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />

  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>

  <style type="text/css">

    .highlight { display: block; background-color: #ddd; }

  </style>