Module: YARD::Templates::Engine

Defined in:
lib/yard/templates/engine.rb

Class Attribute Summary

Class Method Summary

Class Attribute Details

+ (Array<String>) template_paths

The list of registered template paths

Returns:

  • (Array<String>) — the list of registered template paths 


6
7
8
 
# File 'lib/yard/templates/engine.rb', line 6

def template_paths
  @template_paths
end

Class Method Details

+ (void) generate(objects, options = {})

This method returns an undefined value.

Passes a set of objects to the :fulldoc template for full documentation generation. This is called by CLI::Yardoc to most commonly perform HTML documentation generation.

Parameters:



90
91
92
93
94
 
# File 'lib/yard/templates/engine.rb', line 90

def generate(objects, options = {})
  set_default_options(options)
  options[:objects] = objects
  template(options[:template], :fulldoc, options[:format]).run(options)
end

+ (void) register_template_path(path)

This method returns an undefined value.

Registers a new template path in template_paths

Parameters:

  • (String) path — a new template path 


12
13
14
 
# File 'lib/yard/templates/engine.rb', line 12

def register_template_path(path)
  template_paths.push path
end

+ (String) render(options = {})

Renders a template on a code object using a set of default (overridable) options. Either the :object or :type keys must be provided.

If a :serializer key is provided and :serialize is not set to false, the rendered contents will be serialized through the Serializers::Base object. See with_serializer.

Examples:

Renders an object with html formatting 

  Engine.render(:format => :html, :object => obj)

Renders without an object 

  Engine.render(:type => :fulldoc, :otheropts => somevalue)

Parameters:

  • (Hash) options (defaults to: {}) — the options hash

Options Hash (options):

  • (Symbol) :format — default: :text — the default format
  • (Symbol) :type — default: nil — the :object’s type.
  • (Symbol) :template — default: :default — the default template

Returns:

  • (String) — the rendered template 


71
72
73
74
75
76
77
78
79
80
 
# File 'lib/yard/templates/engine.rb', line 71

def render(options = {})
  set_default_options(options)
  mod = template(options[:template], options[:type], options[:format])
  
  if options[:serialize] != false
    with_serializer(options[:object], options[:serializer]) { mod.run(options) }
  else
    mod.run(options)
  end
end

+ (Template) template(*path)

Creates a template module representing the path. Searches on disk for the first directory named path (joined by ’/’) within the template paths and builds a template module for. All other matching directories in other template paths will be included in the generated module as mixins (for overriding).

Parameters:

  • (Array<String, Symbol>) path — a list of path components

Returns:

  • (Template) — the module representing the template

Raises:

  • (ArgumentError) 


24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/yard/templates/engine.rb', line 24

def template(*path)
  from_template = nil
  from_template = path.shift if path.first.is_a?(Template)
  path = path.join('/')
  full_paths = find_template_paths(from_template, path)
  
  path = File.cleanpath(path).gsub('../', '')
  raise ArgumentError, "No such template for #{path}" if full_paths.empty?
  mod = template!(path, full_paths)

  mod
end

+ (Template) template!(path, full_paths = nil)

Forces creation of a template at path within a full_path.

Parameters:

  • (String) path — the path name of the template
  • (Array<String>) full_paths (defaults to: nil) — the full path on disk of the template

Returns:

  • (Template) — the template module representing the path 


42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/yard/templates/engine.rb', line 42

def template!(path, full_paths = nil)
  full_paths ||= [path]
  full_paths = [full_paths] unless full_paths.is_a?(Array)
  name = template_module_name(full_paths.first)
  return const_get(name) rescue NameError 

  mod = const_set(name, Module.new)
  mod.send(:include, Template)
  mod.send(:initialize, path, full_paths)
  mod
end

+ (Object) with_serializer(object, serializer, &block) { ... }

Serializes the results of a block with a serializer object.

Parameters:

Yields:

  • a block whose result will be serialize

Yield Returns:

  • (String) — the contents to serialize

See Also:



103
104
105
106
107
108
109
110
111
 
# File 'lib/yard/templates/engine.rb', line 103

def with_serializer(object, serializer, &block)
  serializer.before_serialize if serializer
  output = yield
  if serializer
    serializer.serialize(object, output)
    serializer.after_serialize(output)
  end
  output
end