graphql-docs 5.2.0 → 6.0.0

data/lib/graphql-docs/generator.rb

@@ -1,16 +1,42 @@
 # frozen_string_literal: true
 
-require 'erb'
-require 'fileutils'
-require 'sass-embedded'
-require 'ostruct'
+require "erb"
+require "fileutils"
+require "sass-embedded"
+require "ostruct"
 
 module GraphQLDocs
+  # Generates HTML documentation files from a parsed GraphQL schema.
+  #
+  # The Generator takes the parsed schema structure and creates individual HTML pages
+  # for each GraphQL type, along with landing pages and static assets. It uses ERB
+  # templates for layout and the Renderer for converting content to HTML.
+  #
+  # @example Basic usage
+  #   generator = GraphQLDocs::Generator.new(parsed_schema, options)
+  #   generator.generate
+  #
+  # @see Parser
+  # @see Renderer
   class Generator
     include Helpers
 
+    # @!attribute [rw] parsed_schema
+    #   @return [Hash] The parsed schema structure from {Parser}
     attr_accessor :parsed_schema
 
+    # Initializes a new Generator instance.
+    #
+    # Sets up ERB templates for all GraphQL types and landing pages. Validates that
+    # all required template files exist before generation begins.
+    #
+    # @param parsed_schema [Hash] The parsed schema from {Parser#parse}
+    # @param options [Hash] Configuration options
+    # @option options [Hash] :templates Paths to ERB template files
+    # @option options [Hash] :landing_pages Paths to landing page files
+    # @option options [Class] :renderer Renderer class to use
+    #
+    # @raise [IOError] If any required template or landing page file is not found
     def initialize(parsed_schema, options)
       @parsed_schema = parsed_schema
       @options = options
@@ -31,9 +57,9 @@ module GraphQLDocs
         end
 
         landing_page_contents = File.read(@options[:landing_pages][sym])
-        metadata = ''
+        metadata = ""
 
-        if File.extname((@options[:landing_pages][sym])) == '.erb'
+        if File.extname(@options[:landing_pages][sym]) == ".erb"
           opts = @options.merge(@options[:landing_pages][:variables]).merge(helper_methods)
           if yaml?(landing_page_contents)
             metadata, landing_page = split_into_metadata_and_contents(landing_page_contents, parse: false)
@@ -49,6 +75,17 @@ module GraphQLDocs
       end
     end
 
+    # Generates all HTML documentation files.
+    #
+    # This is the main generation method that creates:
+    # - Individual pages for each GraphQL type
+    # - Landing pages for type categories
+    # - Static assets (CSS, fonts, images) if using default styles
+    #
+    # @return [Boolean] Returns true on successful generation
+    #
+    # @example
+    #   generator.generate # Creates all docs in output directory
     def generate
       FileUtils.rm_rf(@options[:output_dir]) if @options[:delete_output]
 
@@ -63,44 +100,47 @@ module GraphQLDocs
       create_graphql_scalar_pages
       create_graphql_directive_pages
 
-      write_file('static', 'index', @graphql_index_landing_page, trim: false) unless @graphql_index_landing_page.nil?
+      write_file("static", "index", @graphql_index_landing_page, trim: false) unless @graphql_index_landing_page.nil?
 
-      write_file('static', 'object', @graphql_object_landing_page, trim: false) unless @graphql_object_landing_page.nil?
+      write_file("static", "object", @graphql_object_landing_page, trim: false) unless @graphql_object_landing_page.nil?
 
-      write_file('operation', 'query', @graphql_query_landing_page, trim: false) if !@graphql_query_landing_page.nil? && !has_query
+      write_file("operation", "query", @graphql_query_landing_page, trim: false) if !@graphql_query_landing_page.nil? && !has_query
 
-      write_file('operation', 'mutation', @graphql_mutation_landing_page, trim: false) unless @graphql_mutation_landing_page.nil?
+      write_file("operation", "mutation", @graphql_mutation_landing_page, trim: false) unless @graphql_mutation_landing_page.nil?
 
-      write_file('static', 'interface', @graphql_interface_landing_page, trim: false) unless @graphql_interface_landing_page.nil?
+      write_file("static", "interface", @graphql_interface_landing_page, trim: false) unless @graphql_interface_landing_page.nil?
 
-      write_file('static', 'enum', @graphql_enum_landing_page, trim: false) unless @graphql_enum_landing_page.nil?
+      write_file("static", "enum", @graphql_enum_landing_page, trim: false) unless @graphql_enum_landing_page.nil?
 
-      write_file('static', 'union', @graphql_union_landing_page, trim: false) unless @graphql_union_landing_page.nil?
+      write_file("static", "union", @graphql_union_landing_page, trim: false) unless @graphql_union_landing_page.nil?
 
-      write_file('static', 'input_object', @graphql_input_object_landing_page, trim: false) unless @graphql_input_object_landing_page.nil?
+      write_file("static", "input_object", @graphql_input_object_landing_page, trim: false) unless @graphql_input_object_landing_page.nil?
 
-      write_file('static', 'scalar', @graphql_scalar_landing_page, trim: false) unless @graphql_scalar_landing_page.nil?
+      write_file("static", "scalar", @graphql_scalar_landing_page, trim: false) unless @graphql_scalar_landing_page.nil?
 
-      write_file('static', 'directive', @graphql_directive_landing_page, trim: false) unless @graphql_directive_landing_page.nil?
+      write_file("static", "directive", @graphql_directive_landing_page, trim: false) unless @graphql_directive_landing_page.nil?
 
       if @options[:use_default_styles]
-        assets_dir = File.join(File.dirname(__FILE__), 'layouts', 'assets')
-        FileUtils.mkdir_p(File.join(@options[:output_dir], 'assets'))
+        assets_dir = File.join(File.dirname(__FILE__), "layouts", "assets")
+        FileUtils.mkdir_p(File.join(@options[:output_dir], "assets"))
 
-        css = Sass.compile(File.join(assets_dir, 'css', 'screen.scss')).css
-        File.write(File.join(@options[:output_dir], 'assets', 'style.css'), css)
+        css = Sass.compile(File.join(assets_dir, "css", "screen.scss")).css
+        File.write(File.join(@options[:output_dir], "assets", "style.css"), css)
 
-        FileUtils.cp_r(File.join(assets_dir, 'images'), File.join(@options[:output_dir], 'assets'))
-        FileUtils.cp_r(File.join(assets_dir, 'webfonts'), File.join(@options[:output_dir], 'assets'))
+        FileUtils.cp_r(File.join(assets_dir, "images"), File.join(@options[:output_dir], "assets"))
       end
 
       true
     end
 
+    # Creates HTML pages for GraphQL operation types (Query, Mutation).
+    #
+    # @return [Boolean] Returns true if Query type was found and generated
+    # @api private
     def create_graphql_operation_pages
       graphql_operation_types.each do |query_type|
-        metadata = ''
-        next unless query_type[:name] == graphql_root_types['query']
+        metadata = ""
+        next unless query_type[:name] == graphql_root_types["query"]
 
         unless @options[:landing_pages][:query].nil?
           query_landing_page = @options[:landing_pages][:query]
@@ -115,90 +155,117 @@ module GraphQLDocs
         end
         opts = default_generator_options(type: query_type)
         contents = @graphql_operations_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('operation', 'query', metadata + contents)
+        write_file("operation", "query", metadata + contents)
         return true
       end
       false
     end
 
+    # Creates HTML pages for GraphQL object types.
+    # @return [void]
+    # @api private
     def create_graphql_object_pages
       graphql_object_types.each do |object_type|
         opts = default_generator_options(type: object_type)
 
         contents = @graphql_objects_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('object', object_type[:name], contents)
+        write_file("object", object_type[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL query fields.
+    # @return [void]
+    # @api private
     def create_graphql_query_pages
       graphql_query_types.each do |query|
         opts = default_generator_options(type: query)
 
         contents = @graphql_queries_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('query', query[:name], contents)
+        write_file("query", query[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL mutation fields.
+    # @return [void]
+    # @api private
     def create_graphql_mutation_pages
       graphql_mutation_types.each do |mutation|
         opts = default_generator_options(type: mutation)
 
         contents = @graphql_mutations_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('mutation', mutation[:name], contents)
+        write_file("mutation", mutation[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL interface types.
+    # @return [void]
+    # @api private
     def create_graphql_interface_pages
       graphql_interface_types.each do |interface_type|
         opts = default_generator_options(type: interface_type)
 
         contents = @graphql_interfaces_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('interface', interface_type[:name], contents)
+        write_file("interface", interface_type[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL enum types.
+    # @return [void]
+    # @api private
     def create_graphql_enum_pages
       graphql_enum_types.each do |enum_type|
         opts = default_generator_options(type: enum_type)
 
         contents = @graphql_enums_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('enum', enum_type[:name], contents)
+        write_file("enum", enum_type[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL union types.
+    # @return [void]
+    # @api private
     def create_graphql_union_pages
       graphql_union_types.each do |union_type|
         opts = default_generator_options(type: union_type)
 
         contents = @graphql_unions_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('union', union_type[:name], contents)
+        write_file("union", union_type[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL input object types.
+    # @return [void]
+    # @api private
     def create_graphql_input_object_pages
       graphql_input_object_types.each do |input_object_type|
         opts = default_generator_options(type: input_object_type)
 
         contents = @graphql_input_objects_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('input_object', input_object_type[:name], contents)
+        write_file("input_object", input_object_type[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL scalar types.
+    # @return [void]
+    # @api private
     def create_graphql_scalar_pages
       graphql_scalar_types.each do |scalar_type|
         opts = default_generator_options(type: scalar_type)
 
         contents = @graphql_scalars_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('scalar', scalar_type[:name], contents)
+        write_file("scalar", scalar_type[:name], contents)
       end
     end
 
+    # Creates HTML pages for GraphQL directives.
+    # @return [void]
+    # @api private
     def create_graphql_directive_pages
       graphql_directive_types.each do |directive_type|
         opts = default_generator_options(type: directive_type)
 
         contents = @graphql_directives_template.result(OpenStruct.new(opts).instance_eval { binding })
-        write_file('directive', directive_type[:name], contents)
+        write_file("directive", directive_type[:name], contents)
       end
     end
 
@@ -209,8 +276,8 @@ module GraphQLDocs
     end
 
     def write_file(type, name, contents, trim: true)
-      if type == 'static'
-        if name == 'index'
+      if type == "static"
+        if name == "index"
           path = @options[:output_dir]
         else
           path = File.join(@options[:output_dir], name)
@@ -221,21 +288,59 @@ module GraphQLDocs
         FileUtils.mkdir_p(path)
       end
 
+      metadata = {}
       if yaml?(contents)
         # Split data
-        meta, contents = split_into_metadata_and_contents(contents)
-        @options = @options.merge(meta)
+        metadata, contents = split_into_metadata_and_contents(contents)
       end
 
       if trim
         # normalize spacing so that CommonMarker doesn't treat it as `pre`
-        contents.gsub!(/^\s+$/, '')
-        contents.gsub!(/^\s{4}/m, '  ')
+        contents.gsub!(/^\s+$/, "")
+        contents.gsub!(/^\s{4}/m, "  ")
       end
 
-      filename = File.join(path, 'index.html')
-      contents = @renderer.render(contents, type: type, name: name, filename: filename)
+      filename = File.join(path, "index.html")
+      contents = render_with_metadata(contents, metadata, type: type, name: name, filename: filename)
       File.write(filename, contents) unless contents.nil?
     end
+
+    # Renders content with optional metadata, without polluting @options.
+    #
+    # File Isolation:
+    # This method ensures that YAML frontmatter metadata from one file doesn't
+    # pollute or leak into other files during batch generation. It achieves this
+    # through an immutable options pattern:
+    #
+    # 1. When metadata is present (from YAML frontmatter), a NEW temporary renderer
+    #    is created with merged options, keeping @options and @renderer unchanged.
+    # 2. When no metadata is present, the shared @renderer is used directly
+    #    (safe because @options and @renderer remain unchanged throughout generation).
+    #
+    # This prevents a bug where title or other metadata from file1.md would
+    # persist and incorrectly appear in file2.md if they were processed sequentially.
+    #
+    # Example:
+    #   # file1.md has "title: Custom Title"
+    #   # file2.md has no YAML frontmatter
+    #   # Without this isolation, file2.md would incorrectly get "Custom Title"
+    #
+    # @param contents [String] Content to render
+    # @param metadata [Hash] Metadata extracted from YAML frontmatter
+    # @param type [String] Type category
+    # @param name [String] Type name
+    # @param filename [String] Output filename
+    # @return [String, nil] Rendered HTML content
+    #
+    # @api private
+    def render_with_metadata(contents, metadata, type:, name:, filename:)
+      if metadata.is_a?(Hash) && metadata.any?
+        temp_options = @options.merge(metadata)
+        temp_renderer = @options[:renderer].new(@parsed_schema, temp_options)
+        temp_renderer.render(contents, type: type, name: name, filename: filename)
+      else
+        @renderer.render(contents, type: type, name: name, filename: filename)
+      end
+    end
   end
 end

data/lib/graphql-docs/helpers.rb

@@ -1,77 +1,183 @@
 # frozen_string_literal: true
 
-require 'commonmarker'
-require 'ostruct'
+require "commonmarker"
+require "gemoji"
+require "ostruct"
 
 module GraphQLDocs
+  # 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) %>`.
+  #
+  # @example Using helper methods in templates
+  #   <%= slugify.("My Type Name") %> # => "my-type-name"
+  #   <%= markdownify.("**bold text**") %> # => "<strong>bold text</strong>"
   module Helpers
+    # Regular expression for slugifying strings in a URL-friendly way.
+    # Matches all characters that are not alphanumeric or common URL-safe characters.
     SLUGIFY_PRETTY_REGEXP = Regexp.new("[^[:alnum:]._~!$&'()+,;=@]+").freeze
 
+    # @!attribute [rw] templates
+    #   @return [Hash] Cache of loaded ERB templates for includes
     attr_accessor :templates
 
+    # Converts a string into a URL-friendly slug.
+    #
+    # @param str [String] The string to slugify
+    # @return [String] Lowercase slug with hyphens instead of spaces
+    #
+    # @example
+    #   slugify("My Type Name") # => "my-type-name"
+    #   slugify("Author.firstName") # => "author.firstname"
     def slugify(str)
-      slug = str.gsub(SLUGIFY_PRETTY_REGEXP, '-')
-      slug.gsub!(/^\-|\-$/i, '')
+      slug = str.gsub(SLUGIFY_PRETTY_REGEXP, "-")
+      slug.gsub!(/^-|-$/i, "")
       slug.downcase
     end
 
+    # 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.
+    #
+    # @param filename [String] Name of the template file in the includes directory
+    # @param opts [Hash] Options to pass to the template
+    # @return [String] Rendered HTML content from the template
+    #
+    # @example In an ERB template
+    #   <%= include.("field_table.html", fields: type[:fields]) %>
     def include(filename, opts = {})
       template = fetch_include(filename)
-      opts = { base_url: @options[:base_url], classes: @options[:classes] }.merge(opts)
+      opts = {base_url: @options[:base_url], classes: @options[:classes]}.merge(opts)
       template.result(OpenStruct.new(opts.merge(helper_methods)).instance_eval { binding })
     end
 
+    # Converts a Markdown string to HTML.
+    #
+    # @param string [String] Markdown content to convert
+    # @return [String] HTML output from the Markdown, empty string if input is nil
+    #
+    # @example
+    #   markdownify("**bold**") # => "<strong>bold</strong>"
+    #   markdownify(nil) # => ""
     def markdownify(string)
-      return '' if string.nil?
+      return "" if string.nil?
 
-      type = @options[:pipeline_config][:context][:unsafe] ? :UNSAFE : :DEFAULT
-      ::CommonMarker.render_html(string, type).strip
+      begin
+        # Replace emoji shortcodes before markdown processing
+        string_with_emoji = emojify(string)
+
+        doc = ::Commonmarker.parse(string_with_emoji)
+        html = if @options[:pipeline_config][:context][:unsafe]
+          doc.to_html(options: {render: {unsafe: true}})
+        else
+          doc.to_html
+        end
+        html.strip
+      rescue => e
+        # Log error and return safe fallback
+        warn "Failed to parse markdown: #{e.message}"
+        require "cgi" unless defined?(CGI)
+        CGI.escapeHTML(string)
+      end
+    end
+
+    # Converts emoji shortcodes like :smile: to emoji characters
+    def emojify(string)
+      string.gsub(/:([a-z0-9_+-]+):/) do |match|
+        emoji = Emoji.find_by_alias(Regexp.last_match(1))
+        emoji ? emoji.raw : match
+      end
     end
 
+    # Returns the root types (query, mutation) from the parsed schema.
+    #
+    # @return [Hash] Hash containing 'query' and 'mutation' keys with type names
     def graphql_root_types
       @parsed_schema[:root_types] || []
     end
 
+    # Returns all operation types (Query, Mutation) from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of operation type hashes
     def graphql_operation_types
       @parsed_schema[:operation_types] || []
     end
 
+    # Returns all query types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of query hashes with fields and arguments
     def graphql_query_types
       @parsed_schema[:query_types] || []
     end
 
+    # Returns all mutation types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of mutation hashes with input and return fields
     def graphql_mutation_types
       @parsed_schema[:mutation_types] || []
     end
 
+    # Returns all object types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of object type hashes
     def graphql_object_types
       @parsed_schema[:object_types] || []
     end
 
+    # Returns all interface types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of interface type hashes
     def graphql_interface_types
       @parsed_schema[:interface_types] || []
     end
 
+    # Returns all enum types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of enum type hashes with values
     def graphql_enum_types
       @parsed_schema[:enum_types] || []
     end
 
+    # Returns all union types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of union type hashes with possible types
     def graphql_union_types
       @parsed_schema[:union_types] || []
     end
 
+    # Returns all input object types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of input object type hashes
     def graphql_input_object_types
       @parsed_schema[:input_object_types] || []
     end
 
+    # Returns all scalar types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of scalar type hashes
     def graphql_scalar_types
       @parsed_schema[:scalar_types] || []
     end
 
+    # Returns all directive types from the parsed schema.
+    #
+    # @return [Array<Hash>] Array of directive hashes with locations and arguments
     def graphql_directive_types
       @parsed_schema[:directive_types] || []
     end
 
+    # Splits content into YAML front matter metadata and body content.
+    #
+    # @param contents [String] Content string potentially starting with YAML front matter
+    # @param parse [Boolean] Whether to parse the YAML (true) or return it as a string (false)
+    # @return [Array<(Hash, String), (String, String)>] Tuple of [metadata, content]
+    #
+    # @raise [RuntimeError] If YAML front matter format is invalid
+    # @raise [RuntimeError] If YAML parsing fails
+    # @raise [TypeError] If parsed YAML is not a Hash
     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
@@ -79,20 +185,34 @@ module GraphQLDocs
       # Parse
       begin
         meta = if parse
-                 YAML.safe_load(pieces[2]) || {}
-               else
-                 pieces[2]
-               end
+          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
+
+      # Validate that parsed YAML is a Hash when parsing is enabled
+      if parse && !meta.is_a?(Hash)
+        raise TypeError, "Expected YAML front matter to be a hash, got #{meta.class}"
+      end
+
       [meta, pieces[4]]
     end
 
+    # Checks if content starts with YAML front matter.
+    #
+    # @param contents [String] Content to check
+    # @return [Boolean] True if content starts with YAML front matter delimiters
     def yaml?(contents)
       contents =~ /\A-{3,5}\s*$/
     end
 
+    # Splits content by YAML front matter delimiters.
+    #
+    # @param contents [String] Content to split
+    # @return [Array<String>] Array of content pieces split by YAML delimiters
     def yaml_split(contents)
       contents.split(/^(-{5}|-{3})[ \t]*\r?\n?/, 3)
     end

data/lib/graphql-docs/layouts/assets/_sass/_api-box.scss

@@ -1,5 +1,5 @@
 .api {
-  background: #fafafa;
+  background: var(--bg-tertiary);
   h3 {
     padding: 5px 10px;
   }
@@ -32,7 +32,7 @@
       margin-left: 15px;
       font-size: 0.9em;
       font-weight: 200;
-      color: #000;
+      color: var(--text-primary);
     }
   }
   dd {