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

Constants inherited from Darkfish

Darkfish::BUILTIN_STYLE_ITEMS, Darkfish::DESCRIPTION, Darkfish::ParagraphExcerptRegexpOther, Darkfish::ParagraphExcerptRegexpUnicode, Darkfish::VERSION

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, #render, #render_template, #setup, #template_for, #template_result, #traverse_classes

Constructor Details

#initialize(store, options) ⇒ Aliki

Returns a new instance of Aliki.



14
15
16
17
18
 
# File 'lib/rdoc/generator/aliki.rb', line 14

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.



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/rdoc/generator/aliki.rb', line 72

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.



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

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.



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

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

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



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

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.



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

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