solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/warning/warn_exception.rb

@@ -0,0 +1,10 @@
+module JsDuck
+  module Warning
+
+    # An exception thrown by JsDuck::Warning classes that is supposed
+    # to result in a warning being logged by Logger.
+    class WarnException < Exception
+    end
+
+  end
+end

data/lib/jsduck/web/class_icons.rb

@@ -0,0 +1,76 @@
+require 'jsduck/tag_registry'
+require 'jsduck/logger'
+require 'fileutils'
+
+module JsDuck
+  module Web
+    class ClassIcons
+      class << self
+        # Returns CSS class name for an icon of class
+        def get(cls)
+          class_icon_providers.each do |tag|
+            if cls[tag.tagname]
+              return "icon-#{tag.tagname}"
+            end
+          end
+
+          return "icon-class"
+        end
+
+        # Generates CSS for class icons
+        def css
+          css = []
+          class_icon_providers.each do |tag|
+            css << <<-EOCSS
+              #center-container h1.icon-#{tag.tagname} .class-source-link {
+                  background: url(class-icons/#{tag.tagname}-large.png) no-repeat 0 -5px; }
+              #treecontainer .x-grid-cell-inner .icon-#{tag.tagname} {
+                  background: url(class-icons/#{tag.tagname}.png) no-repeat; }
+              #search-dropdown .icon-#{tag.tagname} {
+                  background: url(class-icons/#{tag.tagname}.png) no-repeat; }
+              #search-dropdown .icon-#{tag.tagname}-redirect {
+                  background: url(class-icons/#{tag.tagname}-redirect.png) no-repeat; }
+              .doctabs .icon-#{tag.tagname} {
+                  background: url(class-icons/#{tag.tagname}.png) no-repeat; }
+            EOCSS
+          end
+          css.join("\n")
+        end
+
+        # Copies all class icons to given destination dir.
+        def write(dir)
+          FileUtils.mkdir(dir)
+
+          icons = {}
+          class_icon_providers.each do |tag|
+            icons[tag.class_icon[:small]] = "#{dir}/#{tag.tagname}.png"
+            icons[tag.class_icon[:large]] = "#{dir}/#{tag.tagname}-large.png"
+            icons[tag.class_icon[:redirect]] = "#{dir}/#{tag.tagname}-redirect.png"
+          end
+
+          icons.each_pair do |source, target|
+            if File.exists?(source)
+              FileUtils.cp(source, target)
+            else
+              Logger.warn(nil, "Class icon file not found", {:filename => source})
+            end
+          end
+        end
+
+        private
+
+        def class_icon_providers
+          @providers ||= generate_class_icon_providers
+        end
+
+        # Find tags with #class_icon and sort them from highest priority to lowest
+        def generate_class_icon_providers
+          TagRegistry.tags.find_all {|t| t.class_icon }.sort do |a, b|
+            a.class_icon[:priority] <=> b.class_icon[:priority]
+          end.reverse
+        end
+      end
+    end
+
+  end
+end

data/lib/jsduck/web/css.rb

@@ -0,0 +1,40 @@
+require 'jsduck/tag_registry'
+require 'jsduck/util/md5'
+require 'jsduck/web/class_icons'
+require 'jsduck/web/member_icons'
+
+module JsDuck
+  module Web
+
+    # Writes the CSS gathered from Tag classes and --css option into given file.
+    # Then Renames the file so it contains an MD5 hash inside it,
+    # returning the resulting fingerprinted name.
+    class Css
+      def initialize(opts)
+        @opts = opts
+      end
+
+      def write(filename)
+        File.open(filename, 'w') {|f| f.write(all_css) }
+        Util::MD5.rename(filename)
+      end
+
+      private
+
+      def all_css
+        [
+          css_from_tags,
+          Web::ClassIcons.css,
+          Web::MemberIcons.css,
+          @opts.css,
+        ].join
+      end
+
+      # Returns all the CSS gathered from @css attributes of tags.
+      def css_from_tags
+        TagRegistry.tags.map(&:css).compact.join("\n")
+      end
+    end
+
+  end
+end

data/lib/jsduck/web/data.rb

@@ -0,0 +1,52 @@
+require 'jsduck/util/json'
+require 'jsduck/util/md5'
+require 'jsduck/web/tree'
+require 'jsduck/web/search'
+require 'jsduck/tag_registry'
+require 'jsduck/member_registry'
+
+module JsDuck
+  module Web
+
+    # Creates big JS file with data for Docs app.
+    class Data
+      def initialize(relations, assets, opts)
+        @relations = relations
+        @assets = assets
+        @opts = opts
+      end
+
+      # Writes classes, guides, videos, and search data to one big .js file.
+      # Then Renames the file so it contains an MD5 hash inside it,
+      # returning the resulting fingerprinted name.
+      def write(filename)
+        js = "Docs = " + Util::Json.generate({
+          :data => {
+            :classes => Web::Tree.create(@relations.classes),
+            :guides => @assets.guides.to_array,
+            :videos => @assets.videos.to_array,
+            :examples => @assets.examples.to_array,
+            :search => Web::Search.new.create(@relations.classes, @assets, @opts),
+            :guideSearch => @opts.search,
+            :tests => @opts.tests,
+            :signatures => TagRegistry.signatures,
+            :memberTypes => MemberRegistry.definitions,
+            :localStorageDb => @opts.local_storage_db,
+            :showPrintButton => @opts.seo,
+            :touchExamplesUi => @opts.touch_examples_ui,
+            :source => @opts.source,
+            :commentsUrl => @opts.comments_url,
+            :commentsDomain => @opts.comments_domain,
+            :message => @opts.message,
+          }
+        }) + ";\n"
+
+        File.open(filename, 'w') {|f| f.write(js) }
+
+        Util::MD5.rename(filename)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/web/index_html.rb

@@ -0,0 +1,105 @@
+require 'jsduck/logger'
+require 'jsduck/util/io'
+require 'jsduck/tag_registry'
+require 'jsduck/version'
+require 'fileutils'
+
+module JsDuck
+  module Web
+
+    # Deals with creation of main HTML or PHP files.
+    class IndexHtml
+      def initialize(assets, opts, paths={})
+        @assets = assets
+        @opts = opts
+        @paths = paths
+      end
+
+      # In normal mode creates index.html.
+      #
+      # When --seo enabled, creates index.php, template.html and print-template.html.
+      def write
+        if @opts.seo
+          FileUtils.cp(@opts.template+"/index.php", @opts.output+"/index.php")
+          create_template_html(@opts.template+"/template.html", @opts.output+"/template.html")
+          create_print_template_html(@opts.template+"/print-template.html", @opts.output+"/print-template.html")
+          create_index_template_html(@opts.template+"/index-template.html", @opts.output+"/index-template.html")
+        else
+          create_template_html(@opts.template+"/template.html", @opts.output+"/index.html")
+        end
+      end
+
+      private
+
+      def create_template_html(in_file, out_file)
+        write_template(in_file, out_file, {
+          "{title}" => @opts.title,
+          "{mobile_redirect}" => @opts.seo ? include_script(@opts.template+"/mobile-redirect.js") : "",
+          "{header}" => header,
+          "{footer}" => footer,
+          "{extjs_path}" => @opts.extjs_path,
+          "{data_path}" => File.basename(@paths[:data]),
+          "{css_path}" => File.basename(@paths[:css]),
+          "{welcome}" => @assets.welcome.to_html("display:none"),
+          "{categories}" => @assets.categories.to_html("display:none"),
+          "{news}" => @assets.news.to_html("display:none"),
+          "{guides}" => @assets.guides.to_html("display:none"),
+          "{head_html}" => @opts.head_html,
+          "{body_html}" => @opts.body_html,
+        })
+      end
+
+      def create_print_template_html(in_file, out_file)
+        write_template(in_file, out_file, {
+          "{title}" => @opts.title,
+          "{header}" => header,
+          "{css_path}" => File.basename(@paths[:css]),
+        })
+      end
+
+      def create_index_template_html(in_file, out_file)
+        categories = @assets.categories.to_html
+        guides = @assets.guides.to_html
+
+        write_template(in_file, out_file, {
+          "{title}" => @opts.title,
+          "{header}" => header,
+          "{categories}" => categories ? "<h1>API Documentation</h1> #{categories}" : "",
+          "{guides}" => guides ? "<h1>Guides</h1> #{guides}" : "",
+          "{css_path}" => File.basename(@paths[:css]),
+        })
+      end
+
+      def include_script(filename)
+        "<script type='text/javascript'>\n" + Util::IO.read(filename) + "\n</script>"
+      end
+
+      def header
+        @opts.title.sub(/^(.*?) +- +/, "<strong>\\1</strong> ")
+      end
+
+      def footer
+        jsduck = "<a href='https://github.com/senchalabs/jsduck'>JSDuck</a>"
+        date = Time.new.strftime('%a %d %b %Y %H:%M:%S')
+
+        footer_text = @opts.footer.gsub(/\{VERSION\}/, JsDuck::VERSION)
+          .gsub(/\{JSDUCK\}/, jsduck)
+          .gsub(/\{DATE\}/, date)
+
+        return "<div id='footer-content' style='display: none'>#{footer_text}</div>"
+      end
+
+      # Opens in_file, replaces {keys} inside it, writes to out_file
+      def write_template(in_file, out_file, replacements)
+        Logger.log("Writing", out_file)
+        html = Util::IO.read(in_file)
+        html.gsub!(/\{\w+\}/) do |key|
+          replacements[key] ? replacements[key] : key
+        end
+        File.open(out_file, 'w') {|f| f.write(html) }
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/web/member_icons.rb

@@ -0,0 +1,43 @@
+require 'jsduck/member_registry'
+require 'fileutils'
+
+module JsDuck
+  module Web
+
+    # Manages member icons.
+    # Generating CSS for them and coping the image files over to output dir.
+    class MemberIcons
+      # Generates CSS for member icons
+      def self.css
+        css = []
+        members_with_icons.each do |m|
+          name = m[:name]
+          rule = ".icon-#{name} { background-image: url(member-icons/#{name}.png); background-repeat: no-repeat; }"
+          css << "#search-dropdown #{rule}"
+          css << ".members .members-section #{rule}"
+          css << ".members .comments-section #{rule}"
+          css << ".class-overview .x-toolbar.member-links #{rule}"
+        end
+        css.join("\n")
+      end
+
+      # Copies all member icons to given destination dir.
+      def self.write(dir)
+        FileUtils.mkdir(dir)
+
+        members_with_icons.each do |m|
+          if File.exists?(m[:icon])
+            FileUtils.cp(m[:icon], "#{dir}/#{m[:name]}.png")
+          else
+            Logger.warn(nil, "Member icon file not found", {:filename => m[:icon]})
+          end
+        end
+      end
+
+      def self.members_with_icons
+        MemberRegistry.definitions.find_all {|m| m[:icon] }
+      end
+    end
+
+  end
+end

data/lib/jsduck/web/search.rb

@@ -0,0 +1,153 @@
+require 'jsduck/web/class_icons'
+require 'jsduck/class_name'
+require 'jsduck/tag_registry'
+
+module JsDuck
+  module Web
+
+    # Creates list of all members in all classes that is used by the
+    # searching feature in UI.
+    class Search
+      # Given list of classes and other assets, returns an array of
+      # hashes describing the search data.
+      def create(classes, assets, opts)
+        list = []
+
+        classes.each do |cls|
+          list << class_node(cls)
+
+          cls[:alternateClassNames].each do |name|
+            list << alt_node(name, cls)
+          end
+
+          cls[:aliases].each_pair do |key, items|
+            items.each do |name|
+              list << alias_node(key, name, cls)
+            end
+          end
+
+          # add all local members, but skip constructors
+          cls[:members].each do |m|
+            list << member_node(m, cls) unless m[:hide] || constructor?(m)
+          end
+        end
+
+        # Don't include guides data when separate guides search engine is provided
+        assets.guides.each_item {|g| list << guide_node(g) } unless opts.search[:url]
+
+        assets.videos.each_item {|v| list << video_node(v) }
+
+        assets.examples.each_item {|e| list << example_node(e) }
+
+        list
+      end
+
+      private
+
+      def constructor?(m)
+        m[:tagname] == :method && m[:name] == "constructor"
+      end
+
+      def alias_node(key, name, cls)
+        return {
+          :name => name,
+          :fullName => alias_display_name(key)+": "+name,
+          :icon => Web::ClassIcons.get(cls) + "-redirect",
+          :url => "#!/api/" + cls[:name],
+          :meta => combine_meta(cls),
+          :sort => 0,
+        }
+      end
+
+      def class_node(cls)
+        return {
+          :name => ClassName.short(cls[:name]),
+          :fullName => cls[:name],
+          :icon => Web::ClassIcons.get(cls),
+          :url => "#!/api/" + cls[:name],
+          :meta => combine_meta(cls),
+          :sort => 1,
+        }
+      end
+
+      def alt_node(name, cls)
+        return {
+          :name => ClassName.short(name),
+          :fullName => name,
+          :type => :class,
+          :icon => Web::ClassIcons.get(cls) + "-redirect",
+          :url => "#!/api/" + cls[:name],
+          :meta => combine_meta(cls),
+          :sort => 2,
+        }
+      end
+
+      def member_node(member, cls)
+        return {
+          :name => member[:name],
+          :fullName => cls[:name] + "." + member[:name],
+          :icon => "icon-" + member[:tagname].to_s,
+          :url => "#!/api/" + cls[:name] + "-" + member[:id],
+          :meta => combine_meta(member),
+          :sort => 3,
+        }
+      end
+
+      def guide_node(guide)
+        return {
+          :name => guide["title"],
+          :fullName => "guide: " + guide["title"],
+          :icon => "icon-guide",
+          :url => "#!/guide/" + guide["name"],
+          :meta => {},
+          :sort => 4,
+        }
+      end
+
+      def video_node(video)
+        return {
+          :name => video["title"],
+          :fullName => "video: " + video["title"],
+          :icon => "icon-video",
+          :url => "#!/video/" + video["name"],
+          :meta => {},
+          :sort => 4,
+        }
+      end
+
+      def example_node(example)
+        return {
+          :name => example["title"],
+          :fullName => "example: " + example["title"],
+          :icon => "icon-example",
+          :url => "#!/example/" + example["name"],
+          :meta => {},
+          :sort => 4,
+        }
+      end
+
+      # Add data for builtin tags with signatures to :meta field.
+      def combine_meta(hash)
+        meta = {}
+        TagRegistry.signatures.each do |s|
+          name = s[:tagname]
+          meta[name] = hash[name] if hash[name]
+        end
+        meta
+      end
+
+      # Some alias types are shown differently.
+      # e.g. instead of "widget:" we show "xtype:"
+      def alias_display_name(key)
+        titles = {
+          "widget" => "xtype",
+          "plugin" => "ptype",
+          "feature" => "ftype",
+        }
+        titles[key] || key
+      end
+
+    end
+
+  end
+end