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

Add --categories command line option. 

The overviewData.json file is no more hard-coded to JSDuck and
is specified through this option.  When left unspecified, the
classes overview list on the main page is left empty.
parent d88fe669

Rakefile

+1 −0
Original line number Diff line number Diff line
@@ -49,6 +49,7 @@ def run_jsduck(extra_options) 
    '--img', '<p><img src="doc-resources/%u" alt="%a"></p>',

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

    "--guides-order", "getting,class,application,layouts,data,grid,tree,drawing,forms,components,theming,direct",

    "--categories", "template/overviewData.json",

    "--output", "#{OUT_DIR}",

  ].concat(extra_options))

bin/jsduck

+5 −0
Original line number Diff line number Diff line
@@ -63,6 +63,11 @@ opts = OptionParser.new do | opts | 
    app.guides_order = list

  end



  opts.on('--categories=PATH',

    "Path to JSON file which defines categories for classes.", " ") do |path|

    app.categories_path = path

  end



  opts.on('-h', '--help', "Prints this help message", " ") do

    puts opts

    exit

lib/jsduck/app.rb

+12 −28
Original line number Diff line number Diff line
@@ -14,6 +14,7 @@ require 'jsduck/timer' 
require 'jsduck/parallel_wrap'

require 'jsduck/logger'

require 'jsduck/guides'

require 'jsduck/categories'

require 'jsduck/jsonp'

require 'json'

require 'fileutils'
@@ -27,6 +28,7 @@ module JsDuck 
    attr_accessor :template_dir

    attr_accessor :guides_dir

    attr_accessor :guides_order

    attr_accessor :categories_path

    attr_accessor :template_links

    attr_accessor :input_files

    attr_accessor :export
@@ -45,6 +47,7 @@ module JsDuck 
      @template_dir = nil

      @guides_dir = nil

      @guides_order = nil

      @categories_path = nil

      @template_links = false

      @input_files = []

      @warnings = true
@@ -92,6 +95,14 @@ module JsDuck 
        @timer.time(:parsing) { @guides.parse_dir(@guides_dir) }

      end



      @categories = Categories.new()

      if @categories_path

        @timer.time(:parsing) do

          @categories.parse(@categories_path)

          @categories.validate(relations)

        end

      end



      clear_dir(@output_dir)

      if @export == :json

        FileUtils.mkdir(@output_dir)
@@ -109,7 +120,7 @@ module JsDuck 
        @timer.time(:generating) { write_tree(@output_dir+"/output/tree.js", relations) }

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

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

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

        @timer.time(:generating) { @categories.write(@output_dir+"/output/overviewData.js") }

        @timer.time(:generating) { @guides.write(@output_dir+"/guides") }

      end
@@ -184,33 +195,6 @@ module JsDuck 
      end

    end



    # prints warnings for missing classes in overviewData.json file,

    # and writes overviewData to .js file

    def write_overview(filename, relations)

      overview = JSON.parse(IO.read(@template_dir+"/overviewData.json"))

      overview_classes = {}



      # Check that each class listed in overview file exists

      overview["categories"].each_pair do |cat_name, cat|

        cat["classes"].each do |cls_name|

          unless relations[cls_name]

            Logger.instance.warn("Class '#{cls_name}' in category '#{cat_name}' not found")

          end

          overview_classes[cls_name] = true

        end

      end



      # Check that each existing non-private class is listed in overview file

      relations.each do |cls|

        unless overview_classes[cls[:name]] || cls[:private]

          Logger.instance.warn("Class '#{cls[:name]}' not found in overview file")

        end

      end



      js = "Docs.overviewData = " + JSON.generate( overview ) + ";"

      File.open(filename, 'w') {|f| f.write(js) }

    end



    # Given all classes, generates namespace tree and writes it

    # in JSON form into a file.

    def write_tree(filename, relations)

lib/jsduck/categories.rb

0 → 100644
+47 −0
Original line number Diff line number Diff line 
require 'jsduck/logger'

require 'json'



module JsDuck



  # Reads in categories and outputs JSON file

  class Categories

    def initialize

      @overview = {"organisation" => [], "categories" => {}}

    end



    # Parses categories in JSON file

    def parse(path)

      @overview = JSON.parse(IO.read(path))

    end



    # Prints warnings for missing classes in categories file

    def validate(relations)

      overview_classes = {}



      # Check that each class listed in overview file exists

      @overview["categories"].each_pair do |cat_name, cat|

        cat["classes"].each do |cls_name|

          unless relations[cls_name]

            Logger.instance.warn("Class '#{cls_name}' in category '#{cat_name}' not found")

          end

          overview_classes[cls_name] = true

        end

      end



      # Check that each existing non-private class is listed in overview file

      relations.each do |cls|

        unless overview_classes[cls[:name]] || cls[:private]

          Logger.instance.warn("Class '#{cls[:name]}' not found in overview file")

        end

      end

    end



    # Writes the categories as JavaScript file

    def write(filename)

      js = "Docs.overviewData = " + JSON.generate( @overview ) + ";"

      File.open(filename, 'w') {|f| f.write(js) }

    end



  end



end