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:



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

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

Instance Attribute Details

#desc ⇒ Object

Returns the value of attribute desc.



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

def desc
  @desc
end

#lines ⇒ Object (readonly)

Returns the value of attribute lines.



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

def lines
  @lines
end

Class Method Details

.documentable_descriptors ⇒ Object 



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

def self.documentable_descriptors
  return Webhookdb::Replicator.registry.
      values.
      select(&:documentable?).
      sort_by(&:name)
end

.replicator_list_md(descriptors) ⇒ Object 



167
168
169
170
171
172
173
174
175
 
# File 'lib/webhookdb/replicator/docgen.rb', line 167

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 



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/webhookdb/replicator/docgen.rb', line 77

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 



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

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 



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/webhookdb/replicator/docgen.rb', line 56

def _intro
  lines << "# #{desc.resource_name_singular} (`#{desc.name}`)"
  if desc.enterprise?
    lines << ""
    lines << "{% include enterprise_integration_list.md %}"
    lines << ""
  end
  if desc.description.present?
    lines << ""
    lines << desc.description
  end
  lines << ""
  lines << "To get set up, run this code from the [WebhookDB CLI](https://webhookdb.com/terminal):"
  lines << "```\nwebhookdb integrations create #{desc.name}\n```"
  if desc.api_docs_url.present?
    lines << ""
    lines << "Source documentation for this API: [#{desc.api_docs_url}](#{desc.api_docs_url})"
  end
  lines << ""
end

#_prevnext ⇒ Object

Raises:



147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/webhookdb/replicator/docgen.rb', line 147

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 



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/webhookdb/replicator/docgen.rb', line 110

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 



136
137
138
139
140
141
142
143
144
145
 
# File 'lib/webhookdb/replicator/docgen.rb', line 136

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 



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

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

#markdown ⇒ Object 



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

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

#pgtype(t) ⇒ Object 



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

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

#refanchor(d) ⇒ Object 



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

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

#refhref(d) ⇒ Object 



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

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

#repl ⇒ Object 



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

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

#sint ⇒ Object 



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

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

#truecheck(b) ⇒ Object 



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

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