graphql-docs 5.2.0 → 6.0.0

data/lib/graphql-docs/parser.rb

@@ -1,23 +1,43 @@
 # frozen_string_literal: true
 
-require 'graphql'
+require "graphql"
 
 module GraphQLDocs
+  # Parses GraphQL schemas into a structured format for documentation generation.
+  #
+  # The Parser takes a GraphQL schema (as a string or schema class) and transforms it
+  # into a normalized hash structure that's easier to work with during HTML generation.
+  # It extracts all types, fields, arguments, and metadata from the schema.
+  #
+  # @example Basic usage
+  #   parser = GraphQLDocs::Parser.new(schema_string, options)
+  #   parsed = parser.parse
+  #
+  # @example Accessing parsed data
+  #   parsed[:object_types] # => Array of object type hashes
+  #   parsed[:query_types]  # => Array of query hashes
   class Parser
     include Helpers
 
+    # @!attribute [r] processed_schema
+    #   @return [Hash] The parsed schema structure containing all GraphQL types
     attr_reader :processed_schema
 
+    # Initializes a new Parser instance.
+    #
+    # @param schema [String, GraphQL::Schema] GraphQL schema as IDL string or schema class
+    # @param options [Hash] Configuration options including the notices proc
+    # @option options [Proc] :notices Proc for adding custom notices to schema members
     def initialize(schema, options)
       @options = options
 
       @options[:notices] ||= ->(_schema_member_path) { [] }
 
       @schema = if schema.is_a?(String)
-                  GraphQL::Schema.from_definition(schema)
-                elsif schema < GraphQL::Schema
-                  schema
-                end
+        GraphQL::Schema.from_definition(schema)
+      elsif schema < GraphQL::Schema
+        schema
+      end
 
       @processed_schema = {
         operation_types: [],
@@ -33,6 +53,34 @@ module GraphQLDocs
       }
     end
 
+    # Parses the GraphQL schema into a structured hash.
+    #
+    # This method processes the entire schema and extracts all types, including:
+    # - Operation types (Query, Mutation)
+    # - Object types
+    # - Interface types
+    # - Enum types
+    # - Union types
+    # - Input object types
+    # - Scalar types
+    # - Directive types
+    #
+    # Each type includes its fields, arguments, deprecation notices, and custom notices.
+    #
+    # @return [Hash] Structured hash containing all parsed schema data with keys:
+    #   - :root_types - Query and Mutation root type names
+    #   - :operation_types - Array of operation type hashes
+    #   - :query_types - Array of query field hashes
+    #   - :mutation_types - Array of mutation field hashes
+    #   - :object_types - Array of object type hashes
+    #   - :interface_types - Array of interface type hashes
+    #   - :enum_types - Array of enum type hashes
+    #   - :union_types - Array of union type hashes
+    #   - :input_object_types - Array of input object type hashes
+    #   - :scalar_types - Array of scalar type hashes
+    #   - :directive_types - Array of directive hashes
+    #
+    # @raise [TypeError] If an unknown GraphQL type is encountered
     def parse
       root_types = {}
       %w[query mutation].each do |operation|
@@ -49,7 +97,7 @@ module GraphQLDocs
           data[:name] = object.graphql_name
           data[:description] = object.description
 
-          if data[:name] == root_types['query']
+          if data[:name] == root_types["query"]
             data[:interfaces] = object.interfaces.map(&:graphql_name).sort
             data[:fields], data[:connections] = fetch_fields(object.fields, object.graphql_name)
             @processed_schema[:operation_types] << data
@@ -57,36 +105,44 @@ module GraphQLDocs
             object.fields.each_value do |query|
               h = {}
 
-              h[:notices] = @options[:notices].call([object.graphql_name, query.graphql_name].join('.'))
+              h[:notices] = @options[:notices].call([object.graphql_name, query.graphql_name].join("."))
               h[:name] = query.graphql_name
               h[:description] = query.description
-              h[:arguments], = fetch_fields(query.arguments, [object.graphql_name, query.graphql_name].join('.'))
+              if query.respond_to?(:deprecation_reason) && !query.deprecation_reason.nil?
+                h[:is_deprecated] = true
+                h[:deprecation_reason] = query.deprecation_reason
+              end
+              h[:arguments], = fetch_fields(query.arguments, [object.graphql_name, query.graphql_name].join("."))
 
               return_type = query.type
               if return_type.unwrap.respond_to?(:fields)
                 h[:return_fields], = fetch_fields(return_type.unwrap.fields, return_type.graphql_name)
               else # it is a scalar return type
-                h[:return_fields], = fetch_fields({ return_type.graphql_name => query }, return_type.graphql_name)
+                h[:return_fields], = fetch_fields({return_type.graphql_name => query}, return_type.graphql_name)
               end
 
               @processed_schema[:query_types] << h
             end
-          elsif data[:name] == root_types['mutation']
+          elsif data[:name] == root_types["mutation"]
             @processed_schema[:operation_types] << data
 
             object.fields.each_value do |mutation|
               h = {}
 
-              h[:notices] = @options[:notices].call([object.graphql_name, mutation.graphql_name].join('.'))
+              h[:notices] = @options[:notices].call([object.graphql_name, mutation.graphql_name].join("."))
               h[:name] = mutation.graphql_name
               h[:description] = mutation.description
-              h[:input_fields], = fetch_fields(mutation.arguments, [object.graphql_name, mutation.graphql_name].join('.'))
+              if mutation.respond_to?(:deprecation_reason) && !mutation.deprecation_reason.nil?
+                h[:is_deprecated] = true
+                h[:deprecation_reason] = mutation.deprecation_reason
+              end
+              h[:input_fields], = fetch_fields(mutation.arguments, [object.graphql_name, mutation.graphql_name].join("."))
 
               return_type = mutation.type
               if return_type.unwrap.respond_to?(:fields)
                 h[:return_fields], = fetch_fields(return_type.unwrap.fields, return_type.graphql_name)
               else # it is a scalar return type
-                h[:return_fields], = fetch_fields({ return_type.graphql_name => mutation }, return_type.graphql_name)
+                h[:return_fields], = fetch_fields({return_type.graphql_name => mutation}, return_type.graphql_name)
               end
 
               @processed_schema[:mutation_types] << h
@@ -109,7 +165,7 @@ module GraphQLDocs
 
           data[:values] = object.values.values.map do |val|
             h = {}
-            h[:notices] = @options[:notices].call([object.graphql_name, val.graphql_name].join('.'))
+            h[:notices] = @options[:notices].call([object.graphql_name, val.graphql_name].join("."))
             h[:name] = val.graphql_name
             h[:description] = val.description
             unless val.deprecation_reason.nil?
@@ -177,7 +233,7 @@ module GraphQLDocs
       object_fields.each_value do |field|
         hash = {}
 
-        hash[:notices] = @options[:notices].call([parent_path, field.graphql_name].join('.'))
+        hash[:notices] = @options[:notices].call([parent_path, field.graphql_name].join("."))
         hash[:name] = field.graphql_name
         hash[:description] = field.description
         if field.respond_to?(:deprecation_reason) && !field.deprecation_reason.nil?
@@ -217,24 +273,24 @@ module GraphQLDocs
       name = type.unwrap.graphql_name
 
       path = if type.unwrap < GraphQL::Schema::Object
-               if name == 'Query'
-                 'operation'
-               else
-                 'object'
-               end
-             elsif type.unwrap < GraphQL::Schema::Scalar
-               'scalar'
-             elsif type.unwrap < GraphQL::Schema::Interface
-               'interface'
-             elsif type.unwrap < GraphQL::Schema::Enum
-               'enum'
-             elsif type.unwrap < GraphQL::Schema::InputObject
-               'input_object'
-             elsif type.unwrap < GraphQL::Schema::Union
-               'union'
-             else
-               raise TypeError, "Unknown type for `#{name}`: `#{type.unwrap.class}`"
-             end
+        if name == "Query"
+          "operation"
+        else
+          "object"
+        end
+      elsif type.unwrap < GraphQL::Schema::Scalar
+        "scalar"
+      elsif type.unwrap < GraphQL::Schema::Interface
+        "interface"
+      elsif type.unwrap < GraphQL::Schema::Enum
+        "enum"
+      elsif type.unwrap < GraphQL::Schema::InputObject
+        "input_object"
+      elsif type.unwrap < GraphQL::Schema::Union
+        "union"
+      else
+        raise TypeError, "Unknown type for `#{name}`: `#{type.unwrap.class}`"
+      end
 
       {
         name: name,

data/lib/graphql-docs/renderer.rb

@@ -1,16 +1,41 @@
 # frozen_string_literal: true
 
-require 'html/pipeline'
-require 'yaml'
-require 'extended-markdown-filter'
-require 'ostruct'
+require "html_pipeline"
+require "gemoji"
+require "yaml"
+require "ostruct"
 
 module GraphQLDocs
+  # Renders documentation content into HTML.
+  #
+  # The Renderer takes parsed schema content and converts it to HTML using html-pipeline.
+  # It applies markdown processing, emoji support, and other filters, then wraps the
+  # result in the default layout template.
+  #
+  # @example Basic usage
+  #   renderer = GraphQLDocs::Renderer.new(parsed_schema, options)
+  #   html = renderer.render(markdown_content, type: 'object', name: 'User')
+  #
+  # @example Custom renderer
+  #   class MyRenderer < GraphQLDocs::Renderer
+  #     def render(contents, type: nil, name: nil, filename: nil)
+  #       # Custom rendering logic
+  #       super
+  #     end
+  #   end
   class Renderer
     include Helpers
 
+    # @!attribute [r] options
+    #   @return [Hash] Configuration options for the renderer
     attr_reader :options
 
+    # Initializes a new Renderer instance.
+    #
+    # @param parsed_schema [Hash] The parsed schema from {Parser#parse}
+    # @param options [Hash] Configuration options
+    # @option options [Hash] :templates Template file paths
+    # @option options [Hash] :pipeline_config html-pipeline configuration
     def initialize(parsed_schema, options)
       @parsed_schema = parsed_schema
       @options = options
@@ -18,51 +43,93 @@ module GraphQLDocs
       @graphql_default_layout = ERB.new(File.read(@options[:templates][:default])) unless @options[:templates][:default].nil?
 
       @pipeline_config = @options[:pipeline_config] || {}
-      pipeline = @pipeline_config[:pipeline] || {}
       context = @pipeline_config[:context] || {}
 
-      filters = pipeline.map do |f|
-        if filter?(f)
-          f
-        else
-          key = filter_key(f)
-          filter = HTML::Pipeline.constants.find { |c| c.downcase == key }
-          # possibly a custom filter
-          if filter.nil?
-            Kernel.const_get(f)
-          else
-            HTML::Pipeline.const_get(filter)
-          end
-        end
-      end
+      # Convert context for html-pipeline 3
+      @pipeline_context = {}
+      @pipeline_context[:unsafe] = context[:unsafe] if context.key?(:unsafe)
+      @pipeline_context[:asset_root] = context[:asset_root] if context.key?(:asset_root)
 
-      @pipeline = HTML::Pipeline.new(filters, context)
+      # html-pipeline 3 uses a simplified API - we'll just use text-to-text processing
+      # since markdown conversion is handled by commonmarker directly
+      @pipeline = nil # We'll handle markdown conversion directly in to_html
     end
 
+    # Renders content into complete HTML with layout.
+    #
+    # This method converts the content through the html-pipeline filters and wraps it
+    # in the default layout template. If the method returns nil, no file will be written.
+    #
+    # @param contents [String] Content to render (typically Markdown)
+    # @param type [String, nil] GraphQL type category (e.g., 'object', 'interface')
+    # @param name [String, nil] Name of the GraphQL type being rendered
+    # @param filename [String, nil] Output filename path
+    # @return [String, nil] Rendered HTML content, or nil to skip file generation
+    #
+    # @example
+    #   html = renderer.render(markdown, type: 'object', name: 'User')
     def render(contents, type: nil, name: nil, filename: nil)
-      opts = { base_url: @options[:base_url], output_dir: @options[:output_dir] }.merge({ type: type, name: name, filename: filename }).merge(helper_methods)
+      # Include all options (like Generator does) to support YAML frontmatter variables like title
+      opts = @options.merge({type: type, name: name, filename: filename}).merge(helper_methods)
 
-      contents = to_html(contents, context: { filename: filename })
+      contents = to_html(contents, context: {filename: filename})
       return contents if @graphql_default_layout.nil?
 
       opts[:content] = contents
       @graphql_default_layout.result(OpenStruct.new(opts).instance_eval { binding })
     end
 
+    # Converts a string to HTML using commonmarker with emoji support.
+    #
+    # @param string [String] Content to convert
+    # @param context [Hash] Additional context (unused, kept for compatibility)
+    # @return [String] HTML output
+    #
+    # @api private
     def to_html(string, context: {})
-      @pipeline.to_html(string, context)
-    end
+      return "" if string.nil?
+      return "" if string.empty?
 
-    private
+      begin
+        # Replace emoji shortcodes before markdown processing
+        string_with_emoji = emojify(string)
+
+        # Commonmarker 2.x uses parse/render API
+        # Parse with GitHub Flavored Markdown extensions enabled by default
+        doc = ::Commonmarker.parse(string_with_emoji)
 
-    def filter_key(str)
-      str.downcase
+        # Convert to HTML - commonmarker 2.x automatically includes:
+        # - GitHub Flavored Markdown (tables, strikethrough, etc.)
+        # - Header anchors with IDs
+        # - Safe HTML by default (unless unsafe mode is enabled)
+        html = if @pipeline_context[:unsafe]
+          doc.to_html(options: {render: {unsafe: true}})
+        else
+          doc.to_html
+        end
+
+        # Strip trailing newline that commonmarker adds
+        html.chomp
+      rescue => e
+        # Log error and return safe fallback
+        warn "Failed to parse markdown: #{e.message}"
+        require "cgi" unless defined?(CGI)
+        CGI.escapeHTML(string.to_s)
+      end
     end
 
-    def filter?(filter)
-      filter < HTML::Pipeline::Filter
-    rescue LoadError, ArgumentError
-      false
+    # Converts emoji shortcodes like :smile: to emoji characters
+    #
+    # @param string [String] Text containing emoji shortcodes
+    # @return [String] Text with shortcodes replaced by emoji
+    # @api private
+    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
+
+    private
   end
 end

data/lib/graphql-docs/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module GraphQLDocs
-  VERSION = '5.2.0'
+  # Current version of the GraphQLDocs gem
+  VERSION = "6.0.0"
 end

data/lib/graphql-docs.rb

@@ -1,14 +1,82 @@
 # frozen_string_literal: true
 
-require 'graphql-docs/helpers'
-require 'graphql-docs/renderer'
-require 'graphql-docs/configuration'
-require 'graphql-docs/generator'
-require 'graphql-docs/parser'
-require 'graphql-docs/version'
+require "graphql-docs/helpers"
+require "graphql-docs/renderer"
+require "graphql-docs/configuration"
+require "graphql-docs/generator"
+require "graphql-docs/parser"
+require "graphql-docs/version"
 
+# Lazy-load the Rack app - only loads if Rack is available
+begin
+  require "graphql-docs/app" if defined?(Rack)
+rescue LoadError
+  # Rack not available, App class won't be loaded
+end
+
+# GraphQLDocs is a library for generating beautiful HTML documentation from GraphQL schemas.
+# It parses GraphQL schema files or schema objects and generates a complete documentation website
+# with customizable templates and styling.
+#
+# @example Generate docs from a file
+#   GraphQLDocs.build(filename: 'schema.graphql')
+#
+# @example Generate docs from a schema string
+#   GraphQLDocs.build(schema: schema_string)
+#
+# @example Generate docs from a schema class
+#   schema = GraphQL::Schema.define { query query_type }
+#   GraphQLDocs.build(schema: schema)
+#
+# @see Configuration For available configuration options
 module GraphQLDocs
   class << self
+    # Builds HTML documentation from a GraphQL schema.
+    #
+    # This is the main entry point for generating documentation. It accepts either a schema file path
+    # or a schema string/object, parses it, and generates a complete HTML documentation website.
+    #
+    # @param options [Hash] Configuration options for generating the documentation
+    # @option options [String] :filename Path to GraphQL schema IDL file
+    # @option options [String, GraphQL::Schema] :schema GraphQL schema as string or schema class
+    # @option options [String] :output_dir ('./output/') Directory where HTML will be generated
+    # @option options [Boolean] :use_default_styles (true) Whether to include default CSS styles
+    # @option options [String] :base_url ('') Base URL to prepend for assets and links
+    # @option options [Boolean] :delete_output (false) Delete output directory before generating
+    # @option options [Hash] :pipeline_config Configuration for html-pipeline rendering
+    # @option options [Class] :renderer (GraphQLDocs::Renderer) Custom renderer class
+    # @option options [Hash] :templates Custom template file paths
+    # @option options [Hash] :landing_pages Custom landing page file paths
+    # @option options [Hash] :classes Additional CSS class names for elements
+    # @option options [Proc] :notices Proc for adding notices to schema members
+    #
+    # @return [Boolean] Returns true on successful generation
+    #
+    # @raise [ArgumentError] If both filename and schema are provided, or if neither is provided
+    # @raise [ArgumentError] If the specified filename does not exist
+    # @raise [TypeError] If filename is not a String
+    # @raise [TypeError] If schema is not a String or GraphQL::Schema
+    #
+    # @example Basic usage with file
+    #   GraphQLDocs.build(filename: 'schema.graphql')
+    #
+    # @example With custom options
+    #   GraphQLDocs.build(
+    #     filename: 'schema.graphql',
+    #     output_dir: './docs',
+    #     base_url: '/api-docs',
+    #     delete_output: true
+    #   )
+    #
+    # @example With custom renderer
+    #   class MyRenderer < GraphQLDocs::Renderer
+    #     def render(contents, type: nil, name: nil)
+    #       # Custom rendering logic
+    #     end
+    #   end
+    #   GraphQLDocs.build(filename: 'schema.graphql', renderer: MyRenderer)
+    #
+    # @see Configuration::GRAPHQLDOCS_DEFAULTS For all available options
     def build(options)
       # do not let user provided values overwrite every single value
       %i[templates landing_pages].each do |opt|
@@ -24,9 +92,9 @@ module GraphQLDocs
       filename = options[:filename]
       schema = options[:schema]
 
-      raise ArgumentError, 'Pass in `filename` or `schema`, but not both!' if !filename.nil? && !schema.nil?
+      raise ArgumentError, "Pass in `filename` or `schema`, but not both!" if !filename.nil? && !schema.nil?
 
-      raise ArgumentError, 'Pass in either `filename` or `schema`' if filename.nil? && schema.nil?
+      raise ArgumentError, "Pass in either `filename` or `schema`" if filename.nil? && schema.nil?
 
       if filename
         raise TypeError, "Expected `String`, got `#{filename.class}`" unless filename.is_a?(String)
@@ -34,10 +102,8 @@ module GraphQLDocs
         raise ArgumentError, "#{filename} does not exist!" unless File.exist?(filename)
 
         schema = File.read(filename)
-      else
-        raise TypeError, "Expected `String` or `GraphQL::Schema`, got `#{schema.class}`" if !schema.is_a?(String) && !schema_type?(schema)
-
-        schema = schema
+      elsif !schema.is_a?(String) && !schema_type?(schema)
+        raise TypeError, "Expected `String` or `GraphQL::Schema`, got `#{schema.class}`"
       end
 
       parser = GraphQLDocs::Parser.new(schema, options)

data/lib/tasks/graphql-docs.rake

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+begin
+  require "graphql-docs"
+
+  namespace :"graphql-docs" do
+    desc "Generate GraphQL documentation from schema"
+    task :generate, [:schema_file, :output_dir, :base_url, :delete_output] do |_t, args|
+      options = {}
+
+      # Prefer task arguments over environment variables
+      options[:filename] = args[:schema_file] || ENV["GRAPHQL_SCHEMA_FILE"]
+      options[:output_dir] = args[:output_dir] || ENV["GRAPHQL_OUTPUT_DIR"]
+      options[:base_url] = args[:base_url] || ENV["GRAPHQL_BASE_URL"]
+
+      # Handle delete_output as a boolean
+      delete_output_arg = args[:delete_output] || ENV["GRAPHQL_DELETE_OUTPUT"]
+      options[:delete_output] = delete_output_arg == "true" if delete_output_arg
+
+      # Check if a schema file is specified
+      if options[:filename].nil?
+        puts "Please specify a GraphQL schema file:"
+        puts ""
+        puts "Using task arguments:"
+        puts "  rake graphql-docs:generate[path/to/schema.graphql]"
+        puts "  rake graphql-docs:generate[schema.graphql,./docs]"
+        puts "  rake graphql-docs:generate[schema.graphql,./docs,/api-docs,true]"
+        puts ""
+        puts "Or using environment variables:"
+        puts "  GRAPHQL_SCHEMA_FILE=path/to/schema.graphql rake graphql-docs:generate"
+        puts ""
+        puts "Available arguments (in order):"
+        puts "  1. schema_file     - Path to GraphQL schema file (required)"
+        puts "  2. output_dir      - Output directory (default: ./output/)"
+        puts "  3. base_url        - Base URL for assets and links (default: '')"
+        puts "  4. delete_output   - Delete output directory before generating (true/false, default: false)"
+        puts ""
+        puts "Available environment variables:"
+        puts "  GRAPHQL_SCHEMA_FILE    - Path to GraphQL schema file (required)"
+        puts "  GRAPHQL_OUTPUT_DIR     - Output directory (default: ./output/)"
+        puts "  GRAPHQL_BASE_URL       - Base URL for assets and links (default: '')"
+        puts "  GRAPHQL_DELETE_OUTPUT  - Delete output directory before generating (true/false)"
+        exit 1
+      end
+
+      puts "Generating GraphQL documentation..."
+      puts "  Schema: #{options[:filename]}"
+      puts "  Output: #{options[:output_dir] || "./output/"}"
+
+      GraphQLDocs.build(options)
+
+      puts "Documentation generated successfully!"
+    end
+  end
+rescue LoadError
+  # graphql-docs not available, skip task definition
+end