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 



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

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 



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
100
 
# File 'lib/webhookdb/replicator/docgen.rb', line 69

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
 
# File 'lib/webhookdb/replicator/docgen.rb', line 56

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:



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

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 



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

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 



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

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 



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

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 



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

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

#refanchor(d) ⇒ Object 



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

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

#refhref(d) ⇒ Object 



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

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 



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

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