solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/format/subproperties.rb

@@ -0,0 +1,64 @@
+require 'jsduck/util/html'
+require 'jsduck/logger'
+require 'jsduck/type_parser'
+
+module JsDuck
+  module Format
+
+    # Helper for recursively formatting subproperties.
+    class Subproperties
+
+      def initialize(formatter)
+        @formatter = formatter
+        @skip_type_parsing = false
+      end
+
+      # Set to true to skip parsing and formatting of types.
+      # Used to skip parsing of SCSS typesdefs.
+      attr_accessor :skip_type_parsing
+
+      # Takes a hash of param, return value, throws value or subproperty.
+      #
+      # - Markdown-formats the :doc field in it.
+      # - Parses the :type field and saves HTML to :html_type.
+      # - Recursively does the same with all items in :properties field.
+      #
+      def format(item)
+        item[:doc] = @formatter.format(item[:doc]) if item[:doc]
+
+        if item[:type]
+          item[:html_type] = format_type(item[:type])
+        end
+
+        if item[:properties]
+          item[:properties].each {|p| format(p) }
+        end
+      end
+
+      # Formats the given type definition string using TypeParser.
+      #
+      # - On success returns HTML-version of the type definition.
+      # - On failure logs error and returns the type string with only HTML escaped.
+      #
+      def format_type(type)
+        # Skip the formatting entirely when type-parsing is turned off.
+        return Util::HTML.escape(type) if @skip_type_parsing
+
+        tp = TypeParser.new(@formatter)
+        if tp.parse(type)
+          tp.out
+        else
+          context = @formatter.doc_context
+          if tp.error == :syntax
+            Logger.warn(:type_syntax, "Incorrect type syntax #{type}", context)
+          else
+            Logger.warn(:type_name, "Unknown type #{type}", context)
+          end
+          Util::HTML.escape(type)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/grouped_asset.rb

@@ -0,0 +1,59 @@
+require 'jsduck/logger'
+
+module JsDuck
+
+  # Parent class for assets that consist of groups.
+  # That is: guides, vides, examples.
+  #
+  # Subclasses must initialize @groups before calling any of the
+  # methods in this class.
+  class GroupedAsset
+    # Should be called from constructor after @groups have been read in,
+    # and after it's been ensured that all items in groupes have names.
+    def build_map_by_name
+      @map_by_name = {}
+      each_item do |item|
+        @map_by_name[item["name"]] = item
+      end
+    end
+
+    # Accesses item by name
+    def [](name)
+      @map_by_name[name]
+    end
+
+    # Iterates over all items in all groups
+    def each_item(group=nil, &block)
+      group = group || @groups
+
+      group.each do |item|
+        if item["items"]
+          each_item(item["items"], &block)
+        else
+          block.call(item)
+        end
+      end
+    end
+
+    def map_items(group=nil, &block)
+      group = group || @groups
+
+      group.map do |item|
+        if item["items"]
+          {
+            "title" => item["title"],
+            "items" => map_items(item["items"], &block)
+          }
+        else
+          block.call(item)
+        end
+      end
+    end
+
+    # Returns all groups as array
+    def to_array
+      @groups
+    end
+  end
+
+end

data/lib/jsduck/guide_anchors.rb

@@ -0,0 +1,39 @@
+require 'cgi'
+
+module JsDuck
+
+  # Transforms in-page links so they won't break docs app #!-navigation.
+  #
+  # For example a link to "#automation" in testing guide will be
+  # replaced with "#!/guide/testing-section-automation" and the link
+  # target ID will be transformed into "testing-section-automation".
+  class GuideAnchors
+
+    def self.transform(html, guide_name)
+      html.gsub(/(<a\s+(?:[^<>]*\s+)?href=['"]#)([^!\/].*?)(['"])/i) do |m|
+        $1 + "!/guide/" + transform_id($2, guide_name) + $3
+
+      end.gsub(/(<a\s+(?:[^<>]*\s+)?name=['"])(.*?)(['"])/i) do |m|
+        $1 + transform_id($2, guide_name) + $3
+
+      end.gsub(/(<\w+\s+(?:[^<>]*\s+)?id=['"])(.*?)(['"])/i) do |m|
+        $1 + transform_id($2, guide_name) + $3
+      end
+    end
+
+    def self.transform_id(id, guide_name)
+      if id =~ /^#{guide_name}-section-/
+        id
+      else
+        # Escape the ID if it's not already escaped.  This check is
+        # needed to avoid re-escaping anchor-links created with
+        # Markdown - these get auto-escaped by RDiscount.
+        id = (id =~ /%[0-9A-F]{2}/) ? id : CGI::escape(id)
+
+        "#{guide_name}-section-#{id}"
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/guide_toc.rb

@@ -0,0 +1,68 @@
+require 'jsduck/util/html'
+require 'jsduck/guide_toc_entry'
+
+module JsDuck
+
+  # Adds Table of Contents section to guide HTML.
+  class GuideToc
+    def initialize(html, guide_name, max_level=2)
+      @html = html
+      @guide_name = guide_name
+
+      @min_level = 2
+      @max_level = max_level
+
+      @toc = GuideTocEntry.new
+      @new_html = []
+    end
+
+    # Inserts table of contents at the top of guide HTML by looking
+    # for headings at or below the specified maximum level.
+    def inject!
+      @html.each_line do |line|
+        if line =~ /^\s*<h([1-6])>(.*?)<\/h[1-6]>$/
+          level = $1.to_i
+          original_text = $2
+          text = Util::HTML.strip_tags(original_text)
+          id = title_to_id(text)
+
+          if include_to_toc?(level)
+            @toc.add(level, id, text)
+          end
+
+          @new_html << "<h#{level} id='#{id}'>#{original_text}</h#{level}>\n"
+        else
+          @new_html << line
+        end
+      end
+
+      inject_toc!
+
+      @new_html.flatten.join
+    end
+
+    private
+
+    def include_to_toc?(level)
+      (@min_level..@max_level).include?(level)
+    end
+
+    def title_to_id(title)
+      @guide_name + "-section-" + CGI::escape(title.downcase.gsub(/ /, "-"))
+    end
+
+    # Injects TOC below first heading if at least 2 items in TOC
+    def inject_toc!
+      return if @toc.count < 2
+
+      @new_html.insert(1, [
+        "<div class='toc'>\n",
+          "<p><strong>Contents</strong></p>\n",
+          @toc.to_html,
+        "</div>\n",
+      ])
+    end
+
+  end
+
+end

data/lib/jsduck/guide_toc_entry.rb

@@ -0,0 +1,54 @@
+require 'jsduck/util/html'
+
+module JsDuck
+
+  # Manages the single TOC entry (with possible subentries).
+  class GuideTocEntry
+    attr_accessor :label, :items
+
+    def initialize(parent=nil)
+      @parent = parent
+      @label = ""
+      @items = []
+      @min_level = 2
+    end
+
+    # Adds entry at the corresponding heading level.
+    def add(level, id, text)
+      if level == @min_level
+        @items << GuideTocEntry.new(self)
+        @items.last.label = "#{prefix} <a href='#!/guide/#{id}'>#{text}</a>\n"
+      else
+        if @items.empty?
+          @items << GuideTocEntry.new(self)
+        end
+        @items.last.add(level-1, id, text)
+      end
+    end
+
+    # Generates the heading counter, like "1.5.4."
+    def prefix
+      (@parent ? @parent.prefix : "") + "#{@items.length}."
+    end
+
+    # Total number of headings in TOC
+    def count
+      @items.map {|item| 1 + item.count}.reduce(0, :+)
+    end
+
+    # Converts to nested HTML list.
+    def to_html
+      return if @items.empty?
+
+      return [
+        "<ul>",
+          @items.map do |item|
+            "<li>#{item.label} #{item.to_html}</li>"
+          end,
+        "</ul>",
+      ].flatten.compact.join("\n")
+    end
+
+  end
+
+end

data/lib/jsduck/guide_writer.rb

@@ -0,0 +1,58 @@
+require 'jsduck/util/parallel'
+require 'jsduck/util/stdout'
+require 'jsduck/util/json'
+require 'jsduck/logger'
+require 'fileutils'
+
+module JsDuck
+
+  # Writes guide data into files in JSON or JSONP format or to STDOUT.
+  class GuideWriter
+    def initialize(exporter_class, guides, opts)
+      @guides = guides
+      @exporter = exporter_class.new(guides, opts)
+    end
+
+    # Writes guide data into given directory or STDOUT when dir == :stdout.
+    #
+    # Extension is either ".json" for normal JSON output
+    # or ".js" for JsonP output.
+    def write(dir, extension)
+      dir == :stdout ? write_stdout : write_dir(dir, extension)
+    end
+
+    private
+
+    def write_stdout
+      json = ParallelWrap.map(all_guides) {|guide| @exporter.export_guide(guide) }.compact
+      Util::Stdout.add(json)
+    end
+
+    def write_dir(dir, extension)
+      FileUtils.mkdir(dir) unless File.exists?(dir)
+      Util::Parallel.each(all_guides) do |guide|
+        filename = dir + "/" + guide["name"] + extension
+        Logger.log("Writing guide", filename)
+        json = @exporter.export_guide(guide)
+        # skip file if exporter returned nil
+        if json
+          if extension == ".json"
+            Util::Json.write_json(filename, json)
+          elsif extension == ".js"
+            Util::Json.write_jsonp(filename, guide["name"], json)
+          else
+            throw "Unexpected file extension: #{extension}"
+          end
+        end
+      end
+    end
+
+    def all_guides
+      arr = []
+      @guides.each_item {|g| arr << g }
+      arr
+    end
+
+  end
+
+end

data/lib/jsduck/guides.rb

@@ -0,0 +1,188 @@
+require 'jsduck/logger'
+require 'jsduck/util/json'
+require 'jsduck/util/io'
+require 'jsduck/util/null_object'
+require 'jsduck/logger'
+require 'jsduck/grouped_asset'
+require 'jsduck/guide_toc'
+require 'jsduck/guide_anchors'
+require 'jsduck/img/dir'
+require 'fileutils'
+
+module JsDuck
+
+  # Reads in guides and converts them to JsonP files
+  class Guides < GroupedAsset
+    # Creates Guides object from filename and formatter
+    def self.create(filename, formatter, opts)
+      if filename
+        Guides.new(filename, formatter, opts)
+      else
+        Util::NullObject.new(:to_array => [], :to_html => "", :[] => nil)
+      end
+    end
+
+    # Parses guides config file
+    def initialize(filename, formatter, opts)
+      @path = File.dirname(filename)
+      @groups = Util::Json.read(filename)
+      @formatter = formatter
+      @opts = opts
+      build_map_by_name
+      load_all_guides
+    end
+
+    # Writes all guides to given dir in JsonP format
+    def write(dir)
+      FileUtils.mkdir(dir) unless File.exists?(dir)
+      each_item {|guide| write_guide(guide, dir) }
+    end
+
+    def load_all_guides
+      each_item do |guide|
+        guide["url"] = resolve_url(guide)
+        guide[:dir] = resolve_dir(guide)
+        guide[:filename] = resolve_filename(guide)
+        guide[:html] = load_guide(guide)
+      end
+    end
+
+    # Modified to_array that excludes the :html from guide nodes
+    def to_array
+      map_items do |item|
+        Hash[item.select {|k, v| k != :html }]
+      end
+    end
+
+    def load_guide(guide)
+      unless File.exists?(guide[:dir])
+        return Logger.warn(:guide, "Guide not found", {:filename => guide[:dir]})
+      end
+      unless File.exists?(guide[:filename])
+        return Logger.warn(:guide, "Guide not found", {:filename => guide[:filename]})
+      end
+      unless js_ident?(guide["name"])
+        # Guide name is also used as JSONP callback method name.
+        return Logger.warn(:guide, "Guide name is not valid JS identifier: #{guide["name"]}", {:filename => guide[:filename]})
+      end
+
+      begin
+        return format_guide(guide)
+      rescue
+        Logger.fatal_backtrace("Error while reading/formatting guide #{guide[:filename]}", $!)
+        exit(1)
+      end
+    end
+
+    def format_guide(guide)
+      @formatter.doc_context = {:filename => guide[:filename], :linenr => 0}
+      @formatter.images = Img::Dir.new(guide[:dir], "guides/#{guide["name"]}")
+      html = @formatter.format(Util::IO.read(guide[:filename]))
+      html = GuideToc.new(html, guide['name'], @opts.guides_toc_level).inject!
+      html = GuideAnchors.transform(html, guide['name'])
+
+      # Report unused images (but ignore the icon files)
+      @formatter.images.get("icon.png")
+      @formatter.images.get("icon-lg.png")
+      @formatter.images.report_unused
+
+      return html
+    end
+
+    def write_guide(guide, dir)
+      return unless guide[:html]
+
+      out_dir = dir + "/" + guide["name"]
+
+      Logger.log("Writing guide", out_dir)
+      # Copy the whole guide dir over
+      FileUtils.cp_r(guide[:dir], out_dir)
+
+      # Ensure the guide has an icon
+      fix_icon(out_dir)
+
+      Util::Json.write_jsonp(out_dir+"/README.js", guide["name"], {:guide => guide[:html], :title => guide["title"]})
+    end
+
+    # Turns guide URL into full path.
+    # If no URL given at all, creates it from guide name.
+    def resolve_url(guide)
+      if guide["url"]
+        File.expand_path(guide["url"], @path)
+      else
+        @path + "/guides/" + guide["name"]
+      end
+    end
+
+    # Detects guide directory.
+    # The URL either points to a file or directory.
+    def resolve_dir(guide)
+      if File.file?(guide["url"])
+        File.expand_path("..", guide["url"])
+      else
+        guide["url"]
+      end
+    end
+
+    # Detects guide filename.
+    # Either use URL pointing to a file or look up README.md from directory.
+    def resolve_filename(guide)
+      if File.file?(guide["url"])
+        guide["url"]
+      else
+        guide[:dir] + "/README.md"
+      end
+    end
+
+    # True when string is valid JavaScript identifier
+    def js_ident?(str)
+      /\A[$\w]+\z/ =~ str
+    end
+
+    # Ensures the guide dir contains icon.png.
+    # When there isn't looks for icon-lg.png and renames it to icon.png.
+    # When neither exists, copies over default icon.
+    def fix_icon(dir)
+      if File.exists?(dir+"/icon.png")
+        # All ok
+      elsif File.exists?(dir+"/icon-lg.png")
+        FileUtils.mv(dir+"/icon-lg.png", dir+"/icon.png")
+      else
+        FileUtils.cp(@opts.template+"/resources/images/default-guide.png", dir+"/icon.png")
+      end
+    end
+
+    # Returns HTML listing of guides
+    def to_html(style="")
+      html = @groups.map do |group|
+        [
+          "<h3>#{group['title']}</h3>",
+          "<ul>",
+          flatten_subgroups(group["items"]).map {|g| "<li><a href='#!/guide/#{g['name']}'>#{g['title']}</a></li>" },
+          "</ul>",
+        ]
+      end.flatten.join("\n")
+
+      return <<-EOHTML
+        <div id='guides-content' style='#{style}'>
+            #{html}
+        </div>
+      EOHTML
+    end
+
+    def flatten_subgroups(items)
+      result = []
+      each_item(items) do |item|
+        result << item
+      end
+      result
+    end
+
+    # Extracts guide icon URL from guide hash
+    def icon_url(guide)
+      "guides/" + guide["name"] + "/icon.png"
+    end
+
+  end
+
+end