Module: GraphQLDocs::Helpers

Included in:
Generator, Parser, Renderer
Defined in:
lib/graphql-docs/helpers.rb

Overview

Helper methods module for use in ERB templates.

This module provides utility methods that can be called from within ERB templates when generating documentation. Methods are available via dot notation in templates, such as <%= slugify.(text) %>.

Examples:

Using helper methods in templates

<%= slugify.("My Type Name") %> # => "my-type-name"
<%= markdownify.("**bold text**") %> # => "<strong>bold text</strong>"

Constant Summary collapse

SLUGIFY_PRETTY_REGEXP =

Regular expression for slugifying strings in a URL-friendly way. Matches all characters that are not alphanumeric or common URL-safe characters.

Regexp.new("[^[:alnum:]._~!$&'()+,;=@]+").freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#templates ⇒ Hash

Returns Cache of loaded ERB templates.

Returns:

  • (Hash) —

    Cache of loaded ERB templates



23
24
25
 
# File 'lib/graphql-docs/helpers.rb', line 23

def templates
  @templates
end

Instance Method Details

#graphql_directive_types ⇒ Array<Hash>

Returns all directive types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of directive hashes with locations and arguments



144
145
146
 
# File 'lib/graphql-docs/helpers.rb', line 144

def graphql_directive_types
  @parsed_schema[:directive_types] || []
end

#graphql_enum_types ⇒ Array<Hash>

Returns all enum types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of enum type hashes with values



116
117
118
 
# File 'lib/graphql-docs/helpers.rb', line 116

def graphql_enum_types
  @parsed_schema[:enum_types] || []
end

#graphql_input_object_types ⇒ Array<Hash>

Returns all input object types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of input object type hashes



130
131
132
 
# File 'lib/graphql-docs/helpers.rb', line 130

def graphql_input_object_types
  @parsed_schema[:input_object_types] || []
end

#graphql_interface_types ⇒ Array<Hash>

Returns all interface types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of interface type hashes



109
110
111
 
# File 'lib/graphql-docs/helpers.rb', line 109

def graphql_interface_types
  @parsed_schema[:interface_types] || []
end

#graphql_mutation_types ⇒ Array<Hash>

Returns all mutation types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of mutation hashes with input and return fields



95
96
97
 
# File 'lib/graphql-docs/helpers.rb', line 95

def graphql_mutation_types
  @parsed_schema[:mutation_types] || []
end

#graphql_object_types ⇒ Array<Hash>

Returns all object types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of object type hashes



102
103
104
 
# File 'lib/graphql-docs/helpers.rb', line 102

def graphql_object_types
  @parsed_schema[:object_types] || []
end

#graphql_operation_types ⇒ Array<Hash>

Returns all operation types (Query, Mutation) from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of operation type hashes



81
82
83
 
# File 'lib/graphql-docs/helpers.rb', line 81

def graphql_operation_types
  @parsed_schema[:operation_types] || []
end

#graphql_query_types ⇒ Array<Hash>

Returns all query types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of query hashes with fields and arguments



88
89
90
 
# File 'lib/graphql-docs/helpers.rb', line 88

def graphql_query_types
  @parsed_schema[:query_types] || []
end

#graphql_root_types ⇒ Hash

Returns the root types (query, mutation) from the parsed schema.

Returns:

  • (Hash) —

    Hash containing 'query' and 'mutation' keys with type names



74
75
76
 
# File 'lib/graphql-docs/helpers.rb', line 74

def graphql_root_types
  @parsed_schema[:root_types] || []
end

#graphql_scalar_types ⇒ Array<Hash>

Returns all scalar types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of scalar type hashes



137
138
139
 
# File 'lib/graphql-docs/helpers.rb', line 137

def graphql_scalar_types
  @parsed_schema[:scalar_types] || []
end

#graphql_union_types ⇒ Array<Hash>

Returns all union types from the parsed schema.

Returns:

  • (Array<Hash>) —

    Array of union type hashes with possible types



123
124
125
 
# File 'lib/graphql-docs/helpers.rb', line 123

def graphql_union_types
  @parsed_schema[:union_types] || []
end

#include(filename, opts = {}) ⇒ String

Includes and renders a partial template file.

This method loads an ERB template from the includes directory and renders it with the provided options. Useful for reusing template fragments.

Examples:

In an ERB template

<%= include.("field_table.html", fields: type[:fields]) %>

Parameters:

  • filename (String) —

    Name of the template file in the includes directory

  • opts (Hash) (defaults to: {}) —

    Options to pass to the template

Returns:

  • (String) —

    Rendered HTML content from the template



50
51
52
53
54
 
# File 'lib/graphql-docs/helpers.rb', line 50

def include(filename, opts = {})
  template = fetch_include(filename)
  opts = { base_url: @options[:base_url], classes: @options[:classes] }.merge(opts)
  template.result(OpenStruct.new(opts.merge(helper_methods)).instance_eval { binding })
end

#markdownify(string) ⇒ String

Converts a Markdown string to HTML.

Examples:

markdownify("**bold**") # => "<strong>bold</strong>"
markdownify(nil) # => ""

Parameters:

  • string (String) —

    Markdown content to convert

Returns:

  • (String) —

    HTML output from the Markdown, empty string if input is nil



64
65
66
67
68
69
 
# File 'lib/graphql-docs/helpers.rb', line 64

def markdownify(string)
  return '' if string.nil?

  type = @options[:pipeline_config][:context][:unsafe] ? :UNSAFE : :DEFAULT
  ::CommonMarker.render_html(string, type).strip
end

#slugify(str) ⇒ String

Converts a string into a URL-friendly slug.

Examples:

slugify("My Type Name") # => "my-type-name"
slugify("Author.firstName") # => "author.firstname"

Parameters:

  • str (String) —

    The string to slugify

Returns:

  • (String) —

    Lowercase slug with hyphens instead of spaces



33
34
35
36
37
 
# File 'lib/graphql-docs/helpers.rb', line 33

def slugify(str)
  slug = str.gsub(SLUGIFY_PRETTY_REGEXP, '-')
  slug.gsub!(/^\-|\-$/i, '')
  slug.downcase
end

#split_into_metadata_and_contents(contents, parse: true) ⇒ Array<(Hash, String), (String, String)>

Splits content into YAML front matter metadata and body content.

Parameters:

  • contents (String) —

    Content string potentially starting with YAML front matter

  • parse (Boolean) (defaults to: true) —

    Whether to parse the YAML (true) or return it as a string (false)

Returns:

  • (Array<(Hash, String), (String, String)>) —

    Tuple of [metadata, content]

Raises:

  • (RuntimeError) —

    If YAML front matter format is invalid

  • (RuntimeError) —

    If YAML parsing fails



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/graphql-docs/helpers.rb', line 156

def split_into_metadata_and_contents(contents, parse: true)
  pieces = yaml_split(contents)
  raise "The file '#{content_filename}' appears to start with a metadata section (three or five dashes at the top) but it does not seem to be in the correct format." if pieces.size < 4

  # Parse
  begin
    meta = if parse
             YAML.safe_load(pieces[2]) || {}
           else
             pieces[2]
           end
  rescue Exception => e # rubocop:disable Lint/RescueException
    raise "Could not parse YAML for #{name}: #{e.message}"
  end
  [meta, pieces[4]]
end

#yaml?(contents) ⇒ Boolean

Checks if content starts with YAML front matter.

Parameters:

  • contents (String) —

    Content to check

Returns:

  • (Boolean) —

    True if content starts with YAML front matter delimiters



177
178
179
 
# File 'lib/graphql-docs/helpers.rb', line 177

def yaml?(contents)
  contents =~ /\A-{3,5}\s*$/
end

#yaml_split(contents) ⇒ Array<String>

Splits content by YAML front matter delimiters.

Parameters:

  • contents (String) —

    Content to split

Returns:

  • (Array<String>) —

    Array of content pieces split by YAML delimiters



185
186
187
 
# File 'lib/graphql-docs/helpers.rb', line 185

def yaml_split(contents)
  contents.split(/^(-{5}|-{3})[ \t]*\r?\n?/, 3)
end