Class: JsDuck::Guides

Inherits:
GroupedAsset show all
Defined in:
lib/jsduck/guides.rb

Overview

Reads in guides and converts them to JsonP files

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from GroupedAsset

#[], #build_map_by_name, #each_item, #map_items

Constructor Details

#initialize(filename, formatter, opts) ⇒ Guides

Parses guides config file



26
27
28
29
30
31
32
33
 
# 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

Class Method Details

.create(filename, formatter, opts) ⇒ Object

Creates Guides object from filename and formatter



17
18
19
20
21
22
23
 
# 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

Instance Method Details

#fix_icon(dir) ⇒ Object

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.



120
121
122
123
124
125
126
127
128
 
# File 'lib/jsduck/guides.rb', line 120

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_dir+"/resources/images/default-guide.png", dir+"/icon.png")
  end
end

#flatten_subgroups(items) ⇒ Object 



148
149
150
151
152
153
154
 
# File 'lib/jsduck/guides.rb', line 148

def flatten_subgroups(items)
  result = []
  each_item(items) do |item|
    result << item
  end
  result
end

#format_guide(guide) ⇒ Object 



72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/jsduck/guides.rb', line 72

def format_guide(guide)
  @formatter.doc_context = {:filename => guide[:filename], :linenr => 0}
  @formatter.images = Img::Dir.new(guide["url"], "guides/#{guide["name"]}")
  html = @formatter.format(Util::IO.read(guide[:filename]))
  html = GuideToc.inject(html, guide['name'])
  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) ⇒ Object

Extracts guide icon URL from guide hash



157
158
159
 
# File 'lib/jsduck/guides.rb', line 157

def icon_url(guide)
  "guides/" + guide["name"] + "/icon.png"
end

#js_ident?(str) ⇒ Boolean

True when string is valid JavaScript identifier

Returns:

  • (Boolean) 


113
114
115
 
# File 'lib/jsduck/guides.rb', line 113

def js_ident?(str)
  /\A[$\w]+\z/ =~ str
end

#load_all_guides ⇒ Object 



41
42
43
44
45
46
47
 
# File 'lib/jsduck/guides.rb', line 41

def load_all_guides
  each_item do |guide|
    guide["url"] = resolve_url(guide)
    guide[:filename] = guide["url"] + "/README.md"
    guide[:html] = load_guide(guide)
  end
end

#load_guide(guide) ⇒ Object 



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/jsduck/guides.rb', line 56

def load_guide(guide)
  return Logger.warn(:guide, "Guide not found", guide["url"]) unless File.exists?(guide["url"])
  return Logger.warn(:guide, "Guide not found", guide[:filename]) unless File.exists?(guide[:filename])
  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"]}", guide[:filename])
  end

  begin
    return format_guide(guide)
  rescue
    Logger.fatal_backtrace("Error while reading/formatting guide #{guide['url']}", $!)
    exit(1)
  end
end

#resolve_url(guide) ⇒ Object

Turns guide URL into full path. If no URL given at all, creates it from guide name.



104
105
106
107
108
109
110
 
# File 'lib/jsduck/guides.rb', line 104

def resolve_url(guide)
  if guide["url"]
    File.expand_path(guide["url"], @path)
  else
    @path + "/guides/" + guide["name"]
  end
end

#to_array ⇒ Object

Modified to_array that excludes the :html from guide nodes



50
51
52
53
54
 
# File 'lib/jsduck/guides.rb', line 50

def to_array
  map_items do |item|
    Hash[item.select {|k, v| k != :html }]
  end
end

#to_html(style = "") ⇒ Object

Returns HTML listing of guides



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/jsduck/guides.rb', line 131

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) ⇒ Object

Writes all guides to given dir in JsonP format



36
37
38
39
 
# 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) ⇒ Object 



87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/jsduck/guides.rb', line 87

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["url"], 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