Commit e862beec authored by Rene Saarsoo's avatar Rene Saarsoo
Browse files

Load guides over JsonP. 

Parsing guides README.md files is now done inside JSDuck, and enabled
when --guides=/some/path option is passed in.  As an added bonus, the
{@link-s} inside guides now also work.

Like with class documentation, we create .js files for guides to
load them over JsonP.
parent ffda64af

bin/jsduck

+7 −0
Original line number Diff line number Diff line
@@ -81,6 +81,13 @@ opts = OptionParser.new do | opts | 
    app.external_classes << classname

  end



  opts.on('--guides=PATH', "Path to guides directory.",

    "Each subdirectory of that is treated as a guide",

    "and is expectd to contain a REAME.md file,",

    "which will be converted into a README.js.") do |path|

    app.guides_dir = path

  end



  opts.on('-v', '--verbose', "This will fill up your console.") do

    app.verbose = true

  end

lib/jsduck/app.rb

+28 −0
Original line number Diff line number Diff line
@@ -21,6 +21,7 @@ module JsDuck 
    # These are basically input parameters for app

    attr_accessor :output_dir

    attr_accessor :template_dir

    attr_accessor :guides_dir

    attr_accessor :template_links

    attr_accessor :input_files

    attr_accessor :verbose
@@ -33,6 +34,7 @@ module JsDuck 
    def initialize

      @output_dir = nil

      @template_dir = nil

      @guides_dir = nil

      @template_links = false

      @input_files = []

      @verbose = false
@@ -75,6 +77,9 @@ module JsDuck 
        @timer.time(:generating) { write_tree(@output_dir+"/output/tree.js", relations) }

        @timer.time(:generating) { write_members(@output_dir+"/output/members.js", relations) }

        @timer.time(:generating) { write_json(@output_dir+"/output", relations) }

        if @guides_dir

          @timer.time(:generating) { write_guides(@guides_dir, @output_dir+"/guides", relations) }

        end

      end



      @timer.report if @verbose
@@ -208,6 +213,29 @@ module JsDuck 
      end

    end



    # Writes JsonP export file for each guide

    def write_guides(in_path, out_path, relations)

      formatter = DocFormatter.new

      formatter.link_tpl = @link_tpl if @link_tpl

      formatter.img_tpl = @img_tpl if @img_tpl

      formatter.relations = relations

      FileUtils.mkdir(out_path)

      Dir.glob(in_path + "/*").each do |in_dir|

        if File.directory?(in_dir)

          guide_name = File.basename(in_dir)

          out_dir = out_path + "/" + guide_name

          puts "Creating guide #{out_dir} ..." if @verbose

          FileUtils.cp_r(in_dir, out_dir)

          guide = formatter.format(IO.read(out_dir + "/README.md"))

          guide.gsub!(/<img src="/, "<img src=\"guides/#{guide_name}/")

          json = JSON.pretty_generate({:guide => guide})

          jsonp = "Ext.data.JsonP." + guide_name + "(" + json + ");"

          File.open(out_dir+"/README.js", 'w') {|f| f.write(jsonp) }

          FileUtils.rm(out_dir + "/README.md")

        end

      end

    end



    def copy_template(template_dir, dir)

      puts "Copying template files to #{dir}..." if @verbose

      FileUtils.cp_r(template_dir, dir)

sdk.sh

+1 −11
Original line number Diff line number Diff line
@@ -12,6 +12,7 @@ ruby bin/jsduck \ 
     --external=Error \

     --link='<a href="#/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>' \

     --img='<p><img src="doc-resources/%u" alt="%a"></p>' \

     --guides=$SDK_DIR/guides \

     --output=$OUT_DIR \

     $SDK_DIR/extjs/src $SDK_DIR/platform/src $SDK_DIR/platform/core/src
@@ -28,14 +29,3 @@ ruby bin/jsduck \ 
cp -r $SDK_DIR/extjs/doc-resources $OUT_DIR/doc-resources

cp -r $SDK_DIR/platform/doc-resources/* $OUT_DIR/doc-resources

# Copy over guides

cp -r $SDK_DIR/guides $OUT_DIR/guides

# Remove documentation_style.md which we don't want

rm $OUT_DIR/guides/documentation_style.md

# convert markdown files in guides to HTML

# also make image links relative to root dir

for dir in $(ls $OUT_DIR/guides); do

    rdiscount $OUT_DIR/guides/$dir/README.md | sed 's/<img src="/<img src="guides\/'$dir'\//;' > $OUT_DIR/guides/$dir/index.html

    rm $OUT_DIR/guides/$dir/README.md

done

template/js/Guides.js

+6 −6
Original line number Diff line number Diff line
@@ -5,7 +5,7 @@ Ext.define("Docs.Guides", { 
    singleton: true,



    /**

     * Loads guide from given URL.

     * Loads guide with given name.

     *

     * @param {String} name  name of the guide

     * @param {Boolean} noHistory  true to not add browser history entry
@@ -13,11 +13,11 @@ Ext.define("Docs.Guides", { 
    load: function(name, noHistory) {

        noHistory || Docs.History.push("/guide/" + name);



        Ext.Ajax.request({

            url: Docs.App.getBaseUrl() + "/guides/" + name + "/index.html",

            success: function(response) {

                var html = response.responseText;

                this.render(html);

        Ext.data.JsonP.request({

            url: Docs.App.getBaseUrl() + "/guides/" + name + "/README.js",

            callbackName: name,

            success: function(json) {

                this.render(json.guide);

            },

            scope: this

        });