Class: RDoc::Generator::Aliki

Inherits:
Darkfish
  • Object
show all
Defined in:
lib/rdoc/generator/aliki.rb

Overview

Aliki theme for RDoc documentation

Author: Stan Lo

Constant Summary collapse

DESCRIPTION = 
'HTML generator, written by Stan Lo'

Constants inherited from Darkfish

Darkfish::BUILTIN_STYLE_ITEMS, Darkfish::ParagraphExcerptRegexpOther, Darkfish::ParagraphExcerptRegexpUnicode

Instance Attribute Summary

Attributes inherited from Darkfish

#asset_rel_path, #base_dir, #classes, #dry_run, #file_output, #files, #json_index, #methods, #modsort, #outputdir, #store, #template_dir

Instance Method Summary collapse

Methods inherited from Darkfish

#assemble_template, #copy_static, #debug_msg, #excerpt, #gen_sub_directories, #generate_ancestor_list, #generate_class, #generate_class_files, #generate_class_index_content, #generate_class_link, #generate_file_files, #generate_index, #generate_page, #generate_servlet_not_found, #generate_servlet_root, #generate_table_of_contents, #get_sorted_module_list, #group_classes_by_namespace_for_sidebar, #install_rdoc_static_file, #refresh_store_data, #render, #render_template, #setup, #template_for, #template_result, #traverse_classes

Constructor Details

#initialize(store, options) ⇒ Aliki

Returns a new instance of Aliki.



16
17
18
19
20
 
# File 'lib/rdoc/generator/aliki.rb', line 16

def initialize(store, options)
  super
  aliki_template_dir = File.expand_path(File.join(__dir__, 'template', 'aliki'))
  @template_dir = Pathname.new(aliki_template_dir)
end

Instance Method Details

#build_search_index ⇒ Object

Build a search index array for Aliki’s searcher.



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
 
# File 'lib/rdoc/generator/aliki.rb', line 74

def build_search_index
  setup

  index = []

  @classes.each do |klass|
    next unless klass.display?

    index << build_class_module_entry(klass)

    klass.constants.each do |const|
      next unless const.display?

      index << build_constant_entry(const, klass)
    end
  end

  @methods.each do |method|
    next unless method.display?

    index << build_method_entry(method)
  end

  index
end

#generate ⇒ Object

Generate documentation. Overrides Darkfish to use Aliki’s own search index instead of the JsonIndex generator.



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/rdoc/generator/aliki.rb', line 26

def generate
  setup

  write_style_sheet
  generate_index
  generate_class_files
  generate_file_files
  generate_table_of_contents
  write_search_index

  copy_static

rescue => e
  debug_msg "%s: %s\n  %s" % [
    e.class.name, e.message, e.backtrace.join("\n  ")
  ]

  raise
end

#resolve_url(rel_prefix, url) ⇒ Object

Resolves a URL for use in templates. Absolute URLs are returned unchanged. Relative URLs are prefixed with rel_prefix to ensure they resolve correctly from any page.



141
142
143
144
145
146
147
148
149
150
 
# File 'lib/rdoc/generator/aliki.rb', line 141

def resolve_url(rel_prefix, url)
  uri = URI.parse(url)
  if uri.absolute?
    url
  else
    "#{rel_prefix}/#{url}"
  end
rescue URI::InvalidURIError
  "#{rel_prefix}/#{url}"
end

#type_signature_html(method_attr, from_path) ⇒ Object

Returns the type signature of method_attr as HTML with linked type names. Returns nil if no type signature is present.



126
127
128
129
130
131
132
133
134
135
 
# File 'lib/rdoc/generator/aliki.rb', line 126

def type_signature_html(method_attr, from_path)
  lines = method_attr.type_signature_lines || @store.rbs_signature_for(method_attr)
  return unless lines

  RDoc::RbsHelper.signature_to_html(
    lines,
    lookup: @store.type_name_lookup,
    from_path: from_path
  )
end

#write_search_index ⇒ Object

Write the search index as a JavaScript file Format: var search_data = { index: […] }

We still write to a .js instead of a .json because loading a JSON file triggers CORS check in browsers. And if we simply inspect the generated pages using file://, which is often the case due to lack of the server mode, the JSON file will be blocked by the browser.



108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/rdoc/generator/aliki.rb', line 108

def write_search_index
  debug_msg "Writing Aliki search index"

  index = build_search_index

  FileUtils.mkdir_p 'js' unless @dry_run

  search_index_path = 'js/search_data.js'
  return if @dry_run

  data = { index: index }
  File.write search_index_path, "var search_data = #{JSON.generate(data)};"
end

#write_style_sheet ⇒ Object

Copy only the static assets required by the Aliki theme. Unlike Darkfish we don’t ship embedded fonts or image sprites, so limit the asset list to keep generated documentation lightweight.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/rdoc/generator/aliki.rb', line 51

def write_style_sheet
  debug_msg "Copying Aliki static files"
  options = { verbose: $DEBUG_RDOC, noop: @dry_run }

  install_rdoc_static_file @template_dir + 'css/rdoc.css', "./css/rdoc.css", options

  unless @options.template_stylesheets.empty?
    FileUtils.cp @options.template_stylesheets, '.', **options
  end

  Dir[(@template_dir + 'js/**/*').to_s].each do |path|
    next if File.directory?(path)
    next if File.basename(path).start_with?('.')

    dst = Pathname.new(path).relative_path_from(@template_dir)

    install_rdoc_static_file @template_dir + path, dst, options
  end
end