class JsDuck::Guides
Reads in guides and converts them to JsonP files
Public Class Methods
create(filename, formatter, opts)
click to toggle source
Creates Guides
object from filename and formatter
# File lib/jsduck/guides.rb, line 17 def self.create(filename, formatter, opts) if filename Guides.new(filename, formatter, opts) else Util::NullObject.new(:to_array => [], :to_html => "", :[] => nil) end end
new(filename, formatter, opts)
click to toggle source
Parses guides config file
# File lib/jsduck/guides.rb, line 26 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
Public Instance Methods
fix_icon(dir)
click to toggle source
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.
# File lib/jsduck/guides.rb, line 145 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
flatten_subgroups(items)
click to toggle source
# File lib/jsduck/guides.rb, line 173 def flatten_subgroups(items) result = [] each_item(items) do |item| result << item end result end
format_guide(guide)
click to toggle source
# File lib/jsduck/guides.rb, line 77 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
icon_url(guide)
click to toggle source
Extracts guide icon URL from guide hash
# File lib/jsduck/guides.rb, line 182 def icon_url(guide) "guides/" + guide["name"] + "/icon.png" end
js_ident?(str)
click to toggle source
True when string is valid JavaScript identifier
# File lib/jsduck/guides.rb, line 138 def js_ident?(str) /\A[$\w]+\z/ =~ str end
load_all_guides()
click to toggle source
# File lib/jsduck/guides.rb, line 41 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
load_guide(guide)
click to toggle source
# File lib/jsduck/guides.rb, line 57 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
resolve_dir(guide)
click to toggle source
Detects guide directory. The URL either points to a file or directory.
# File lib/jsduck/guides.rb, line 119 def resolve_dir(guide) if File.file?(guide["url"]) File.expand_path("..", guide["url"]) else guide["url"] end end
resolve_filename(guide)
click to toggle source
Detects guide filename. Either use URL pointing to a file or look up README.md from directory.
# File lib/jsduck/guides.rb, line 129 def resolve_filename(guide) if File.file?(guide["url"]) guide["url"] else guide[:dir] + "/README.md" end end
resolve_url(guide)
click to toggle source
Turns guide URL into full path. If no URL given at all, creates it from guide name.
# File lib/jsduck/guides.rb, line 109 def resolve_url(guide) if guide["url"] File.expand_path(guide["url"], @path) else @path + "/guides/" + guide["name"] end end
to_array()
click to toggle source
Modified to_array
that excludes the :html from guide nodes
# File lib/jsduck/guides.rb, line 51 def to_array map_items do |item| Hash[item.select {|k, v| k != :html }] end end
to_html(style="")
click to toggle source
Returns HTML listing of guides
# File lib/jsduck/guides.rb, line 156 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
write(dir)
click to toggle source
Writes all guides to given dir in JsonP format
# File lib/jsduck/guides.rb, line 36 def write(dir) FileUtils.mkdir(dir) unless File.exists?(dir) each_item {|guide| write_guide(guide, dir) } end
write_guide(guide, dir)
click to toggle source
# File lib/jsduck/guides.rb, line 92 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