Commit 615f84a9 authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Parser-side expansion of inline examples. 

The code of inline examples is now inserted inside the HTML by
JSDuck parser.

Completely removed the code for doing Ajax loading of examples.
This currently also removed the support for Gists from Github.
parent a9a767cc

Rakefile

+1 −0
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}",

bin/jsduck

+4 −0
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:",

lib/jsduck/app.rb

+3 −0
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
@@ -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

+15 −9
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.
@@ -48,8 +52,6 @@ module JsDuck 
    # name actually exists.

    attr_accessor :relations



    @@example_counter = 0



    def initialize

      @class_context = ""

      @doc_context = {}
@@ -57,7 +59,7 @@ module JsDuck 
      @relations = {}

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

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

      @example_tpl = '<div class="inline-example" id="eg%i" rel="%u"></div>'

      @example_tpl = '<pre class="inline-example">%a</pre>'

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

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

      @example_re = /\{@example\s+(\S*?)\s*\}/m
@@ -169,14 +171,18 @@ module JsDuck 
      end

    end



    # applies the example template

    def example(url)

    # Replaces example template with example read from file

    def example(path)

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

        case $1

        when '%u'

          url

        when '%i'

          @@example_counter += 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

spec/doc_formatter_spec.rb

+14 −0
Original line number Diff line number Diff line
@@ -113,6 +113,20 @@ describe JsDuck::DocFormatter do 
        '<img src="some/image.png" alt="foo&quot;bar"/>'

    end



    # {@example ...}



    it "replaces {@example foo.js} with source from foo.js file" do

      @formatter.get_example = lambda { "Some code" }

      @formatter.replace('{@example foo.js}').should ==

        '<pre class="inline-example">Some code</pre>'

    end



    it "escapes HTML inside source of {@example}" do

      @formatter.get_example = lambda { "Some <html> code" }

      @formatter.replace('{@example foo.js}').should ==

        '<pre class="inline-example">Some &lt;html&gt; code</pre>'

    end



    # auto-conversion of identifiable ClassNames to links

    describe "auto-detect" do

      before do