Class: RDoc::Generator::Aliki

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Darkfish`
Instance Chain: self, `Darkfish`, ERB::Util
Inherits:	RDoc::Generator::Darkfish Object RDoc::Generator::Darkfish RDoc::Generator::Aliki
Defined in:	lib/rdoc/generator/aliki.rb

Overview

Aliki theme for ::RDoc::RDoc documentation

Author: Stan Lo

Constant Summary

`Darkfish` - Inherited

BUILTIN_STYLE_ITEMS, DESCRIPTION, ParagraphExcerptRegexpOther, ParagraphExcerptRegexpUnicode, VERSION

Class Method Summary

.new(store, options) ⇒ Aliki constructor

`Darkfish` - Inherited

.new	Initialize a few instance variables before we start.

Instance Attribute Summary

`Darkfish` - Inherited

#asset_rel_path	The relative path to style sheets and javascript.
#base_dir	The path to generate files into, combined with `--op` from the options for a full path.
#classes	Classes and modules to be used by this generator, not necessarily displayed.
#dry_run	No files will be written when dry_run is true.
#file_output	When false the generate methods return a String instead of writing to a file.
#files	Files to be displayed by this generator.
#json_index	The JSON index generator for this `Darkfish` generator.
#methods	Methods to be displayed by this generator.
#modsort	Sorted list of classes and modules to be displayed by this generator.
#outputdir	The output directory.
#store	The `::RDoc::Store` that is the source of the generated content.
#template_dir	The directory where the template files live.

Instance Method Summary

#build_search_index

Build a search index array for Aliki’s searcher.
#generate

Generate documentation.
#resolve_url(rel_prefix, url)

Resolves a URL for use in templates.
#write_search_index

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

Copy only the static assets required by the Aliki theme.
#build_class_module_entry(klass) private
#build_constant_entry(const, parent) private
#build_method_entry(method) private

`Darkfish` - Inherited

#assemble_template	Creates a template from its components and the `body_file`.
#copy_static	Copies static files from the static_path into the output directory.
#debug_msg	Output progress information if debugging is enabled.
#excerpt	Returns an excerpt of the comment for usage in meta description tags.
#gen_sub_directories	Create the directories the generated docs will live in if they don’t already exist.
#generate	Build the initial indices and output objects based on an array of `::RDoc::TopLevel` objects containing the extracted information.
#generate_ancestor_list,
#generate_class	Generates a class file for `klass`
#generate_class_files	Generate a documentation file for each class and module.
#generate_class_index_content, #generate_class_link,
#generate_file_files	Generate a documentation file for each file.
#generate_index	Generate an index page which lists all the classes which are documented.
#generate_page	Generate a page file for `file`
#generate_servlet_not_found	Generates the 404 page for the `::RDoc::RDoc` servlet.
#generate_servlet_root	Generates the servlet root page for the `::RDoc::RDoc` servlet.
#generate_table_of_contents	Generate an index page which lists all the classes which are documented.
#get_sorted_module_list	Return a list of the documented modules sorted by salience first, then by name.
#group_classes_by_namespace_for_sidebar,
#render	Renders the ERb contained in `file_name` relative to the template directory and returns the result based on the current context.
#render_template	Load and render the erb template in the given `template_file` and write it out to `out_file`.
#setup	Prepares for generation of output from the current directory.
#template_for	Retrieves a cache template for `file`, if present, or fills the cache.
#template_result	Creates the result for `template` with `context`.
#traverse_classes,
#write_style_sheet	Copy over the stylesheet into the appropriate place in the output directory.
#generate_nesting_namespaces_breadcrumb, #nesting_namespaces_to_class_modules, #install_rdoc_static_file

Constructor Details

.new(store, options) ⇒ `Aliki`

[ GitHub ]

# 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_class_module_entry(klass) (private)

[ GitHub ]

# File 'lib/rdoc/generator/aliki.rb', line 137


def build_class_module_entry(klass)
  type = case klass
         when RDoc::NormalClass then 'class'
         when RDoc::NormalModule then 'module'
         else 'class'
         end

  entry = {
    name: klass.name,
    full_name: klass.full_name,
    type: type,
    path: klass.path
  }

  snippet = klass.search_snippet
  entry[:snippet] = snippet unless snippet.empty?
  entry
end

#build_constant_entry(const, parent) (private)

[ GitHub ]

# File 'lib/rdoc/generator/aliki.rb', line 171


def build_constant_entry(const, parent)
  entry = {
    name: const.name,
    full_name: "#{parent.full_name}::#{const.name}",
    type: 'constant',
    path: parent.path
  }

  snippet = const.search_snippet
  entry[:snippet] = snippet unless snippet.empty?
  entry
end

#build_method_entry(method) (private)

[ GitHub ]

# File 'lib/rdoc/generator/aliki.rb', line 156


def build_method_entry(method)
  type = method.singleton ? 'class_method' : 'instance_method'

  entry = {
    name: method.name,
    full_name: method.full_name,
    type: type,
    path: method.path
  }

  snippet = method.search_snippet
  entry[:snippet] = snippet unless snippet.empty?
  entry
end

#build_search_index

Build a search index array for Aliki’s searcher.

[ GitHub ]

# 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

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

[ GitHub ]

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

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.

[ GitHub ]

# 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

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.

[ GitHub ]

# 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

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.

[ GitHub ]

# 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

Class: RDoc::Generator::Aliki

Overview

Constant Summary

Darkfish - Inherited

Class Method Summary

Darkfish - Inherited

Instance Attribute Summary

Darkfish - Inherited

Instance Method Summary

Darkfish - Inherited

Constructor Details

.new(store, options) ⇒ Aliki

Instance Method Details

#build_class_module_entry(klass) (private)

#build_constant_entry(const, parent) (private)

#build_method_entry(method) (private)

#build_search_index

#generate

#resolve_url(rel_prefix, url)

#write_search_index

#write_style_sheet

`Darkfish` - Inherited

`Darkfish` - Inherited

`Darkfish` - Inherited

`Darkfish` - Inherited

.new(store, options) ⇒ `Aliki`