Module: Howdoc::Templates

Defined in:
lib/howdoc/templates.rb

Overview

Page chrome lives here, never in the code that records steps. Directories are searched most-recently-registered first and the gem's own set is always searched last, so an application overrides one file by mirroring its path and leaves the rest alone. The layout is borrowed from YARD, which has been proving it works for well over a decade.

Defined Under Namespace

Classes: Context, MissingTemplate

Constant Summary collapse

DEFAULT_ROOT = 
File.expand_path('../../templates', __dir__)
DEFAULT_NAME = 
'default'

Class Method Summary collapse

Class Method Details

.compiled(path) ⇒ Object

Haml compiles a template into Ruby once and then renders it; a suite that writes a hundred guides should pay for that compilation once.



57
58
59
60
 
# File 'lib/howdoc/templates.rb', line 57

def compiled(path)
  @compiled ||= {}
  @compiled[path] ||= Haml::Template.new(path)
end

.find(relative, template: DEFAULT_NAME) ⇒ Object

Finds relative (for example "document/html/layout.haml") in the first search path that has it, falling back to the default template name so a partial theme only has to carry the files it actually changes.



42
43
44
45
46
47
48
49
 
# File 'lib/howdoc/templates.rb', line 42

def find(relative, template: DEFAULT_NAME)
  candidates = search_paths.flat_map do |root|
    [File.join(root, template, relative), File.join(root, DEFAULT_NAME, relative)]
  end

  candidates.uniq.find { |path| File.file?(path) } ||
    raise(MissingTemplate, "no template found for #{relative.inspect} in #{search_paths.inspect}")
end

.install_assets(into) ⇒ Object

Copies everything under an "assets" directory of every search path into the output directory, later paths first so an application's file wins.



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/howdoc/templates.rb', line 64

def install_assets(into)
  FileUtils.mkdir_p(into)

  search_paths.reverse_each do |root|
    assets = File.join(root, DEFAULT_NAME, 'assets')
    next unless File.directory?(assets)

    Dir.glob(File.join(assets, '*')).each { |file| FileUtils.cp(file, into) }
  end
end

.render(relative, assigns = {}) ⇒ Object 



51
52
53
 
# File 'lib/howdoc/templates.rb', line 51

def render(relative, assigns = {})
  compiled(find(relative)).render(Context.new(assigns))
end

.search_paths ⇒ Object 



35
36
37
 
# File 'lib/howdoc/templates.rb', line 35

def search_paths
  Howdoc.config.template_paths + [DEFAULT_ROOT]
end