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, #to_array

Constructor Details

#initialize(filename, formatter, opts) ⇒ Guides

Parses guides config file



22
23
24
25
26
27
28
 
# File 'lib/jsduck/guides.rb', line 22

def initialize(filename, formatter, opts)
  @path = File.dirname(filename)
  @groups = JsonDuck.read(filename)
  build_map_by_name("Two guides have the same name")
  @formatter = formatter
  @opts = opts
end

Class Method Details

.create(filename, formatter, opts) ⇒ Object

Creates Guides object from filename and formatter



13
14
15
16
17
18
19
 
# File 'lib/jsduck/guides.rb', line 13

def self.create(filename, formatter, opts)
  if filename
    Guides.new(filename, formatter, opts)
  else
    NullObject.new(:to_array => [], :to_html => "", :[] => nil)
  end
end

Instance Method Details

#add_toc(guide, html) ⇒ Object

Creates table of contents at the top of guide by looking for <h2> elements in HTML.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/jsduck/guides.rb', line 73

def add_toc(guide, html)
  toc = [
    "<div class='toc'>\n",
    "<p><strong>Contents</strong></p>\n",
    "<ol>\n",
  ]
  new_html = []
  i = 0
  html.each_line do |line|
    if line =~ /^<h2>(.*)<\/h2>$/
      i += 1
      toc << "<li><a href='#!/guide/#{guide['name']}-section-#{i}'>#{$1}</a></li>\n"
      new_html << "<h2 id='#{guide['name']}-section-#{i}'>#{$1}</h2>\n"
    else
      new_html << line
    end
  end
  toc << "</ol>\n"
  toc << "</div>\n"
  # Inject TOC at below first heading if at least 2 items in TOC
  if i >= 2
    new_html.insert(1, toc)
    new_html.flatten.join
  else
    html
  end
end

#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.



62
63
64
65
66
67
68
69
70
 
# File 'lib/jsduck/guides.rb', line 62

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

#icon_url(guide) ⇒ Object

Extracts guide icon URL from guide hash



120
121
122
 
# File 'lib/jsduck/guides.rb', line 120

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

#to_html ⇒ Object

Returns HTML listing of guides



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/jsduck/guides.rb', line 102

def to_html
  html = @groups.map do |group|
    [
      "<h3>#{group['title']}</h3>",
      "<ul>",
      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='display:none'>
        #{html}
    </div>
  EOHTML
end

#write(dir) ⇒ Object

Writes all guides to given dir in JsonP format



31
32
33
34
 
# File 'lib/jsduck/guides.rb', line 31

def write(dir)
  FileUtils.mkdir(dir) unless File.exists?(dir)
  each_item {|guide| write_guide(guide, dir) }
end

#write_guide(guide, dir) ⇒ Object 



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/jsduck/guides.rb', line 36

def write_guide(guide, dir)
  in_dir = @path + "/guides/" + guide["name"]
  out_dir = dir + "/" + guide["name"]
  return Logger.instance.warn(:guide, "Guide #{in_dir} not found") unless File.exists?(in_dir)

  guide_file = in_dir + "/README.md"
  return Logger.instance.warn(:guide, "README.md not found in #{in_dir}") unless File.exists?(guide_file)

  Logger.instance.log("Writing guide", out_dir)
  # Copy the whole guide dir over
  FileUtils.cp_r(in_dir, out_dir)

  # Ensure the guide has an icon
  fix_icon(out_dir)

  @formatter.doc_context = {:filename => guide_file, :linenr => 0}
  name = File.basename(in_dir)
  @formatter.img_path = "guides/#{name}"
  html = add_toc(guide, @formatter.format(IO.read(guide_file)))

  JsonDuck.write_jsonp(out_dir+"/README.js", name, {:guide => html, :title => guide["title"]})
end