Class: Howdoc::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/howdoc/configuration.rb

Overview

Everything an application is allowed to decide: where guides are written, what they are called, which templates dress them and how the index is ordered. The engine itself holds no application knowledge, so anything that would otherwise be hardcoded belongs here.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



78
79
80
81
82
83
84
85
 
# File 'lib/howdoc/configuration.rb', line 78

def initialize
  reset_defaults
  @template_paths = []
  @locale_paths = []
  @field_label = nil
  @sort_key = nil
  @group_label = nil
end

Instance Attribute Details

#enabled ⇒ Object

Guides are only generated when this is true. Keep it tied to an environment variable so an ordinary test run stays fast.



15
16
17
 
# File 'lib/howdoc/configuration.rb', line 15

def enabled
  @enabled
end

#formats ⇒ Object

Writers to run for every finished document, in order.



23
24
25
 
# File 'lib/howdoc/configuration.rb', line 23

def formats
  @formats
end

#host ⇒ Object

Public host name of the documented application. It appears in the prose for visit, where telling the reader to open "localhost:9200" would be useless.



20
21
22
 
# File 'lib/howdoc/configuration.rb', line 20

def host
  @host
end

#illustrate_actions ⇒ Object

Whether an action -- a click, a choice, something typed -- is illustrated as well as narrated. Off by default: a picture belongs where the reader arrives somewhere new, not after every button. Turning it on is what makes the pointer worth having, so a guide shows every click.



59
60
61
 
# File 'lib/howdoc/configuration.rb', line 59

def illustrate_actions
  @illustrate_actions
end

#install_assets ⇒ Object

Whether the templates' assets directory is copied into the output. An application whose templates link its own stylesheets turns this off.



67
68
69
 
# File 'lib/howdoc/configuration.rb', line 67

def install_assets
  @install_assets
end

#locale_paths ⇒ Object (readonly)

Globs of translation files to add to I18n's load path. The gem's English is loaded first so an application only translates what it wants to change.



76
77
78
 
# File 'lib/howdoc/configuration.rb', line 76

def locale_paths
  @locale_paths
end

#locales ⇒ Object

The languages the application publishes its guides in. A test runs in one language, but every guide it records is written in all of these, so a second language costs a translation file rather than a second test run.

These are also the locales an index is built for. Left nil, a guide is written only in the language the suite is running in, and only the locales that actually produced a guide get an index.



32
33
34
 
# File 'lib/howdoc/configuration.rb', line 32

def locales
  @locales
end

#marker ⇒ Object

Whether a screenshot points at what the step is about: an arrow on the button being pressed, a highlight around the words being looked for. Off leaves the pictures exactly as the browser rendered them.



41
42
43
 
# File 'lib/howdoc/configuration.rb', line 41

def marker
  @marker
end

#marker_colour ⇒ Object

The colour of that arrow and highlight. Red by convention, because a guide is read at a glance and red is the one colour an interface rarely uses for anything else.



46
47
48
 
# File 'lib/howdoc/configuration.rb', line 46

def marker_colour
  @marker_colour
end

#marker_dim ⇒ Object

Dims the rest of the page around what is marked. Emphatic, and worth it for a crowded screen; off by default because it changes every picture.



50
51
52
 
# File 'lib/howdoc/configuration.rb', line 50

def marker_dim
  @marker_dim
end

#marker_size ⇒ Object

How tall the drawn pointer is, in CSS pixels.



53
54
55
 
# File 'lib/howdoc/configuration.rb', line 53

def marker_size
  @marker_size
end

#preserved_files ⇒ Object

Files in the output directory that the clean task must leave alone, typically hand-maintained landing pages.



63
64
65
 
# File 'lib/howdoc/configuration.rb', line 63

def preserved_files
  @preserved_files
end

#root ⇒ Object

Directory the generated guides are written into, relative to the working directory unless given as an absolute path.



11
12
13
 
# File 'lib/howdoc/configuration.rb', line 11

def root
  @root
end

#screenshot_height ⇒ Object

Screenshots are taken at this height unless the step asked for a full page, so that guides do not mix wildly different image proportions.



36
37
38
 
# File 'lib/howdoc/configuration.rb', line 36

def screenshot_height
  @screenshot_height
end

#template_paths ⇒ Object (readonly)

Directories searched for templates, most recently registered first. The gem's own directory is always searched last, so an application overrides a single file by mirroring its path rather than copying the whole set.



72
73
74
 
# File 'lib/howdoc/configuration.rb', line 72

def template_paths
  @template_paths
end

Instance Method Details

#enabled? ⇒ Boolean

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/howdoc/configuration.rb', line 137

def enabled?
  !!@enabled
end

#field_label(&block) ⇒ Object

How a form field locator becomes something a reader recognises. The default turns user_email into "email", which suits Rails' own naming. Applications with their own conventions replace it wholesale.



114
115
116
117
118
 
# File 'lib/howdoc/configuration.rb', line 114

def field_label(&block)
  return @field_label = block if block

  @field_label ||= ->(locator) { Howdoc::Narrator.humanize_locator(locator) }
end

#group_label(&block) ⇒ Object

Names the index section a document belongs under, or nil for no section. Receives a Howdoc::Registry::Record, so it decides from the heading, the identifier or the file name -- there is nowhere else for a section to come from once a guide is a page like any other.



131
132
133
134
135
 
# File 'lib/howdoc/configuration.rb', line 131

def group_label(&block)
  return @group_label = block if block

  @group_label ||= ->(_record) {}
end

#illustrate_actions? ⇒ Boolean

Returns:

  • (Boolean) 


145
146
147
 
# File 'lib/howdoc/configuration.rb', line 145

def illustrate_actions?
  !!@illustrate_actions
end

#marker? ⇒ Boolean

Returns:

  • (Boolean) 


141
142
143
 
# File 'lib/howdoc/configuration.rb', line 141

def marker?
  !!@marker
end

#register_locale_path(glob) ⇒ Object 



107
108
109
 
# File 'lib/howdoc/configuration.rb', line 107

def register_locale_path(glob)
  @locale_paths << glob.to_s
end

#register_template_path(path) ⇒ Object 



103
104
105
 
# File 'lib/howdoc/configuration.rb', line 103

def register_template_path(path)
  @template_paths.unshift(path.to_s)
end

#reset_defaults ⇒ Object 



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/howdoc/configuration.rb', line 87

def reset_defaults
  @root = 'doc/howdoc'
  @enabled = false
  @host = nil
  @formats = %i[html]
  @locales = nil
  @screenshot_height = 940
  @marker = true
  @marker_colour = '#e11d48'
  @marker_dim = false
  @marker_size = 52
  @illustrate_actions = false
  @preserved_files = %w[index.html .keep]
  @install_assets = true
end

#sort_key(&block) ⇒ Object

Sorts documents in the index. Receives a Howdoc::Registry::Record.



121
122
123
124
125
 
# File 'lib/howdoc/configuration.rb', line 121

def sort_key(&block)
  return @sort_key = block if block

  @sort_key ||= ->(record) { record.heading.to_s }
end