Class: Yattho::YARD::LegacyGatsbyBackend

Inherits:
Backend
  • Object
show all
Defined in:
lib/yattho/yard/legacy_gatsby_backend.rb

Overview

Backend that generates documentation for the legacy, Gatsby-powered PVC docsite.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DocsHelper

#link_to_accessibility, #link_to_component, #link_to_heading_practices, #link_to_octicons, #link_to_system_arguments_docs, #link_to_typography_docs, #one_of, #pretty_value, #status_module_and_short_name

Constructor Details

#initialize(registry) ⇒ LegacyGatsbyBackend

Returns a new instance of LegacyGatsbyBackend.



34
35
36
 
# File 'lib/yattho/yard/legacy_gatsby_backend.rb', line 34

def initialize(registry)
  @registry = registry
end

Instance Attribute Details

#registry ⇒ Object (readonly)

Returns the value of attribute registry.



32
33
34
 
# File 'lib/yattho/yard/legacy_gatsby_backend.rb', line 32

def registry
  @registry
end

Class Method Details

.parse_example_tag(tag) ⇒ Object 



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/yattho/yard/legacy_gatsby_backend.rb', line 15

def parse_example_tag(tag)
  name = tag.name
  description = nil
  code = nil

  if tag.text.include?("@description")
    splitted = tag.text.split(/@description|@code/)
    description = splitted.second.gsub(/^[ \t]{2}/, "").strip
    code = splitted.last.gsub(/^[ \t]{2}/, "").strip
  else
    code = tag.text
  end

  [name, description, code]
end

Instance Method Details

#generate ⇒ Object 



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
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
100
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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/yattho/yard/legacy_gatsby_backend.rb', line 38

def generate
  args_for_components = []
  errors = []

  each_component do |component|
    docs = registry.find(component)
    status_path = docs.status_module.nil? ? "" : "#{docs.status_module}/"

    metadata = docs.metadata.merge(
      source: source_url(component),
      lookbook: lookbook_url(component),
      path: "docs/content/components/#{status_path}#{docs.short_name.downcase}.md",
      example_path: example_path(component),
      require_js_path: require_js_path(component)
    )

    path = Pathname.new(metadata[:path])
    path.dirname.mkpath unless path.dirname.exist?

    File.open(path, "w") do |f|
      f.puts("---")
      f.puts("title: #{metadata[:title]}")
      f.puts("componentId: #{metadata[:component_id]}")
      f.puts("status: #{metadata[:status]}")
      f.puts("source: #{metadata[:source]}")
      f.puts("a11yReviewed: #{metadata[:a11y_reviewed]}")
      f.puts("lookbook: #{metadata[:lookbook]}") if preview_exists?(component)
      f.puts("---")
      f.puts
      f.puts("import Example from '#{metadata[:example_path]}'")

      if docs.requires_js?
        f.puts("import RequiresJSFlash from '#{metadata[:require_js_path]}'")
        f.puts
        f.puts("<RequiresJSFlash />")
      end

      f.puts
      f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
      f.puts
      f.puts(view_context.render(inline: docs.base_docstring))

      if docs.tags(:deprecated).any?
        f.puts
        f.puts("## Deprecation")
        docs.tags(:deprecated).each do |tag|
          f.puts
          f.puts view_context.render(inline: tag.text)
        end
      end

      if docs.tags(:accessibility).any?
        f.puts
        f.puts("## Accessibility")
        docs.tags(:accessibility).each do |tag|
          f.puts
          f.puts view_context.render(inline: tag.text)
        end
      end

      errors << { component.name => { arguments: "No argument documentation found" } } unless docs.params.any?

      f.puts
      f.puts("## Arguments")
      f.puts
      f.puts("| Name | Type | Default | Description |")
      f.puts("| :- | :- | :- | :- |")

      documented_params = docs.params.map(&:name)
      component_params = component.instance_method(:initialize).parameters.map { |p| p.last.to_s }

      if (documented_params & component_params).size != component_params.size
        err = { arguments: {} }
        (component_params - documented_params).each do |arg|
          err[:arguments][arg] = "Not documented"
        end

        errors << { component.name => err }
      end

      args = []
      docs.params.each do |tag|
        default_value = pretty_default_value(tag, component)

        args << {
          "name" => tag.name,
          "type" => tag.types.join(", "),
          "default" => default_value,
          "description" => view_context.render(inline: tag.text.squish)
        }

        f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default_value} | #{view_context.render(inline: tag.text.squish)} |")
      end

      component_args = {
        "component" => metadata[:title],
        "status" => component.status.to_s,
        "source" => metadata[:source],
        "lookbook" => metadata[:lookbook],
        "parameters" => args
      }

      args_for_components << component_args

      if docs.slot_methods.any?
        f.puts
        f.puts("## Slots")

        docs.slot_methods.each do |slot_docs|
          emit_method(slot_docs, component, f)
        end
      end

      example_tags = docs.constructor.tags(:example)

      if example_tags.any?
        f.puts
        f.puts("## Examples")

        example_tags.each do |tag|
          name, description, code = parse_example_tag(tag)
          f.puts
          f.puts("### #{name}")
          if description
            f.puts
            f.puts(view_context.render(inline: description.squish))
          end
          f.puts
          html = view_context.render(inline: code)
          f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
          f.puts
          f.puts("```erb")
          f.puts(code.to_s)
          f.puts("```")
        end
      elsif manifest.components_with_examples.include?(component)
        errors << { component.name => { example: "No examples found" } }
      end
    end
  end

  # Build system arguments docs from BaseComponent
  system_args_docs = registry.find(Yattho::BaseComponent)

  File.open("docs/content/system-arguments.md", "w") do |f|
    f.puts("---")
    f.puts("title: System arguments")
    f.puts("---")
    f.puts
    f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
    f.puts
    f.puts(system_args_docs.base_docstring)
    f.puts

    f.puts(view_context.render(inline: system_args_docs.constructor.base_docstring))
  end

  [args_for_components, errors]
end