Class: Webhookdb::Replicator::Docgen

Inherits:
Object
  • Object
show all
Defined in:
lib/webhookdb/replicator/docgen.rb

Overview

Write docs for docs.webhookdb.com Jekyll site.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(desc) ⇒ Docgen

Returns a new instance of Docgen.

Parameters:



17
18
19
20
21
 
# File 'lib/webhookdb/replicator/docgen.rb', line 17

def initialize(desc)
  @desc = desc
  @lines = []
  @documentable_descriptors = self.class.documentable_descriptors
end

Instance Attribute Details

#desc ⇒ Object

Returns the value of attribute desc.



13
14
15
 
# File 'lib/webhookdb/replicator/docgen.rb', line 13

def desc
  @desc
end

#lines ⇒ Object (readonly)

Returns the value of attribute lines.



14
15
16
 
# File 'lib/webhookdb/replicator/docgen.rb', line 14

def lines
  @lines
end

Class Method Details

.documentable_descriptors ⇒ Object 



5
6
7
8
9
 
# File 'lib/webhookdb/replicator/docgen.rb', line 5

def self.documentable_descriptors
  return Webhookdb::Replicator.registry.values.reject do |repl|
    repl.name.start_with?("webhookdb_", "fake_")
  end.sort_by(&:name)
end

.replicator_list_md(descriptors) ⇒ Object 



158
159
160
161
162
163
164
165
166
 
# File 'lib/webhookdb/replicator/docgen.rb', line 158

def self.replicator_list_md(descriptors)
  lines = []
  descriptors.each do |d|
    line = "- [#{d.resource_name_singular}]({% link _integrations/#{d.name}.md %})"
    line += " ([Enterprise]({% link docs/enterprise.md %}) only)" if d.enterprise
    lines << line
  end
  return lines.join("\n")
end

Instance Method Details

#_features ⇒ Object 



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/webhookdb/replicator/docgen.rb', line 68

def _features
  lines << "## Features"
  lines << ""
  lines << "<dl>"
  if (dep = desc.dependency_descriptor)
    lines << "<dt>Depends on</dt>"
    lines << "<dd>To use this replicator, you will need #{refanchor(dep)}. " \
             "You'll be prompted to create it if you haven't.</dd>"
    lines << ""
  end
  deps = @documentable_descriptors.select { |d| d.dependency_descriptor == desc }
  if deps.any?
    lines << "<dt>Dependents</dt>"
    lines << "<dd>This replicator is required for the creation of the following dependents:"
    lines << "<ul>"
    deps.each { |d| lines << "<li>#{refanchor(d)}</li>" }
    lines << "</ul>"
    lines << "</dd>"
    lines << ""
  end
  lines << "<dt>Supports Webhooks</dt>"
  lines << "<dd>#{boolmoji(desc.supports_webhooks?)}</dd>"
  lines << "<dt>Supports Backfilling</dt>"
  lines << "<dd>#{boolmoji(desc.supports_backfill?)}</dd>"
  if desc.enterprise?
    lines << "<dt>Enterprise Only</dt>"
    lines << "<dd>Yes</dd>"
  end
  lines << ""
  lines << "</dl>"
  lines << ""
end

#_frontmatter ⇒ Object 



45
46
47
48
49
50
51
52
53
 
# File 'lib/webhookdb/replicator/docgen.rb', line 45

def _frontmatter
  lines << "---"
  lines << "title: #{desc.resource_name_singular}"
  lines << "layout: home"
  idx = @documentable_descriptors.index(desc)
  lines << "nav_order: #{(idx + 1) * 10}"
  lines << "---"
  lines << ""
end

#_intro ⇒ Object 



55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/webhookdb/replicator/docgen.rb', line 55

def _intro
  lines << "# #{desc.resource_name_singular} (`#{desc.name}`)"
  if desc.description.present?
    lines << ""
    lines << desc.description
  end
  if desc.api_docs_url.present?
    lines << ""
    lines << "Docs for this API: [#{desc.api_docs_url}](#{desc.api_docs_url})"
  end
  lines << ""
end

#_prevnext ⇒ Object

Raises:



138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/webhookdb/replicator/docgen.rb', line 138

def _prevnext
  idx = @documentable_descriptors.index(desc)
  raise Webhookdb::InvariantViolation if idx.nil?
  prevtxt = nexttxt = ""
  if (rprev = idx.zero? ? nil : @documentable_descriptors[idx - 1])
    prevtxt = "prev='_integrations/#{rprev.name}.md' prevLabel='#{rprev.name}' "
  end
  if (rnext = idx == (@documentable_descriptors.size - 1) ? nil : @documentable_descriptors[idx + 1])
    nexttxt = "next='_integrations/#{rnext.name}.md' nextLabel='#{rnext.name}'"
  end
  lines << "{% include prevnext.html #{prevtxt}#{nexttxt} %}"
  lines << ""
end

#_schema ⇒ Object 



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/webhookdb/replicator/docgen.rb', line 101

def _schema
  lines << "## Schema"
  lines << ""
  lines << "Tables replicated from #{desc.resource_name_plural} have this schema.
Note that the data types listed are for Postgres;
when [replicating to other databases]({% link _concepts/replication_databases.md %}),
other data types maybe used."
  lines << ""
  lines << "| Column | Type | Indexed |"
  columns = [repl.primary_key_column, repl.remote_key_column]
  columns.concat(repl.storable_columns)
  columns << repl.data_column
  columns.each do |c|
    name = "`#{c.name}`"
    (name += "*") if c.name == :data
    lines << "| #{name} | `#{pgtype(c.type)}` | #{truecheck(c.index)} |"
  end
  lines << ""
  lines << <<~S
    <span class="fs-3">* The `data` column contains the raw payload from the webhook or API.
    In many cases there is no canonical form, like if a webhook and API request return
    two different versions of the same resource.
    In that case we try to keep the most coherent and detailed resource."</span>
  S
end

#_tabledef ⇒ Object 



127
128
129
130
131
132
133
134
135
136
 
# File 'lib/webhookdb/replicator/docgen.rb', line 127

def _tabledef
  lines << "## Table definition"
  lines << ""
  lines << "This definition can also be generated through `webhookdb fixture #{desc.name}`."
  lines << ""
  lines << "```sql"
  lines << repl.create_table_modification.to_s
  lines << "```"
  lines << ""
end

#boolmoji(b) ⇒ Object 



154
 
# File 'lib/webhookdb/replicator/docgen.rb', line 154

def boolmoji(b) = b ? "✅" : "❌"

#markdown ⇒ Object 



35
36
37
38
39
40
41
42
43
 
# File 'lib/webhookdb/replicator/docgen.rb', line 35

def markdown
  _frontmatter
  _intro
  _features
  _schema
  _tabledef
  _prevnext
  return lines.join("\n")
end

#pgtype(t) ⇒ Object 



156
 
# File 'lib/webhookdb/replicator/docgen.rb', line 156

def pgtype(t) = Webhookdb::DBAdapter::PG::COLTYPE_MAP[t]

#refanchor(d) ⇒ Object 



153
 
# File 'lib/webhookdb/replicator/docgen.rb', line 153

def refanchor(d) = "<a href=\"#{refhref(d)}\">#{d.name}</a>"

#refhref(d) ⇒ Object 



152
 
# File 'lib/webhookdb/replicator/docgen.rb', line 152

def refhref(d) = "{% link _integrations/#{d.name}.md %}"

#repl ⇒ Object 



31
32
33
 
# File 'lib/webhookdb/replicator/docgen.rb', line 31

def repl
  @repl ||= desc.ctor[sint]
end

#sint ⇒ Object 



23
24
25
26
27
28
29
 
# File 'lib/webhookdb/replicator/docgen.rb', line 23

def sint
  @sint ||= Webhookdb::ServiceIntegration.new(
    service_name: desc.name,
    opaque_id: "svi_fixture",
    table_name: desc.name + "_fixture",
  )
end

#truecheck(b) ⇒ Object 



155
 
# File 'lib/webhookdb/replicator/docgen.rb', line 155

def truecheck(b) = b ? "✅" : ""