Class: Howdoc::Document

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

Overview

One guide: the identity a test gave it, plus the steps recorded while that test ran. A document collects everything in memory and is written out once, so a writer always sees the whole guide rather than a half-built page.

A test runs in one language but a guide is published in all of them, so a document holds nothing that a language would change. Every such thing -- the heading, the sentences, the file name -- belongs to an Edition, and a document has one per language.

Constant Summary collapse

INDIVISIBLE =

Letters that carry no accent to strip: they are their own character, so Unicode decomposition leaves them untouched and a filename filter would otherwise drop them entirely.

{
  'ß' => 'ss', 'æ' => 'ae', 'œ' => 'oe', 'ø' => 'o',
  'đ' => 'd', 'ð' => 'd', 'ł' => 'l', 'þ' => 'th'
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:, title:, locales:, permalink: nil, intro: nil) ⇒ Document

title and intro are whatever the test knew: a string in the language it was written in, or a hash keyed by locale when the test itself knows more than one. Either way a translation under howdoc.documents wins, so a guide gets a heading in a language no test speaks.



27
28
29
30
31
32
33
34
35
 
# File 'lib/howdoc/document.rb', line 27

def initialize(id:, title:, locales:, permalink: nil, intro: nil)
  @id = id
  @title = title
  @intro = intro
  @permalink = permalink
  @locales = Array(locales).map(&:to_sym)
  @steps = []
  @counter = 0
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



21
22
23
 
# File 'lib/howdoc/document.rb', line 21

def id
  @id
end

#locales ⇒ Object (readonly)

Returns the value of attribute locales.



21
22
23
 
# File 'lib/howdoc/document.rb', line 21

def locales
  @locales
end

#permalink ⇒ Object (readonly)

Returns the value of attribute permalink.



21
22
23
 
# File 'lib/howdoc/document.rb', line 21

def permalink
  @permalink
end

#steps ⇒ Object (readonly)

Returns the value of attribute steps.



21
22
23
 
# File 'lib/howdoc/document.rb', line 21

def steps
  @steps
end

Class Method Details

.slugify(string) ⇒ Object

Deliberately not ActiveSupport's parameterize: the engine has no business dragging Rails into a project that only wanted a documentation generator.

Accents are decomposed and their marks dropped rather than deleted whole, so an Estonian title turns into "kuidas_lisada_noue" instead of the unreadable "kuidas_lisada_n_ue" a plain ASCII filter would leave behind.



87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/howdoc/document.rb', line 87

def self.slugify(string)
  string
    .to_s
    .downcase
    .gsub(/[#{INDIVISIBLE.keys.join}]/, INDIVISIBLE)
    .unicode_normalize(:nfd)
    .gsub(/\p{Mn}/, '')
    .downcase
    .gsub(/[^a-z0-9]+/, '_')
    .gsub(/\A_+|_+\z/, '')
end

Instance Method Details

#dir ⇒ Object 



76
 
# File 'lib/howdoc/document.rb', line 76

def dir = primary.dir

#editions ⇒ Object 



37
38
39
 
# File 'lib/howdoc/document.rb', line 37

def editions
  @editions ||= locales.map { |locale| Edition.new(self, locale) }
end

#heading ⇒ Object 



75
 
# File 'lib/howdoc/document.rb', line 75

def heading = primary.heading

#image_dir ⇒ Object 



77
 
# File 'lib/howdoc/document.rb', line 77

def image_dir = primary.image_dir

#image_filename(number) ⇒ Object 



79
 
# File 'lib/howdoc/document.rb', line 79

def image_filename(number) = primary.image_filename(number)

#intro_for(locale) ⇒ Object 



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

def intro_for(locale)
  Narrator.document_text(:intro, key: translation_key, locale:, default: in_locale(@intro, locale))
end

#last_step ⇒ Object 



68
69
70
 
# File 'lib/howdoc/document.rb', line 68

def last_step
  steps.last
end

#locale ⇒ Object 



49
50
51
 
# File 'lib/howdoc/document.rb', line 49

def locale
  primary.locale
end

#new_step(**attributes) ⇒ Object 



61
62
63
64
65
66
 
# File 'lib/howdoc/document.rb', line 61

def new_step(**attributes)
  @counter += 1
  step = Step.new(number: @counter, **attributes)
  steps << step
  step
end

#path(extension) ⇒ Object 



78
 
# File 'lib/howdoc/document.rb', line 78

def path(extension) = primary.path(extension)

#primary ⇒ Object

The edition a test is recording into. Screenshots are taken while the browser is still on the page, long before the other editions are written, so they are saved where this one keeps its pictures and copied across when the guides are written.



45
46
47
 
# File 'lib/howdoc/document.rb', line 45

def primary
  editions.first
end

#slug ⇒ Object

What the recording edition answers, asked of the document itself, because that is what a recorder has in its hand.



74
 
# File 'lib/howdoc/document.rb', line 74

def slug = primary.slug

#title_for(locale) ⇒ Object 



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

def title_for(locale)
  Narrator.document_text(:title, key: translation_key, locale:, default: in_locale(@title, locale))
end