Merge pull request #169 from brettchalupa/docs

Document Ruby code

Author: brettchalupa

.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--markup-provider commonmarker
+--output-dir doc
+--protected
+--no-private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md

README.md

@@ -198,8 +198,8 @@ To customize the colors, create a custom CSS file and load it after the default
 Then reference it in your custom template by overriding the `default` template and adding a link to your stylesheet:
 
 ```html
-<link rel="stylesheet" href="<%= base_url %>/assets/style.css">
-<link rel="stylesheet" href="<%= base_url %>/assets/custom-theme.css">
+<link rel="stylesheet" href="<%= base_url %>/assets/style.css" />
+<link rel="stylesheet" href="<%= base_url %>/assets/custom-theme.css" />
 ```
 
 ## Configuration
@@ -291,6 +291,40 @@ painless as possible.
 Upcoming work for the project is organized publicly via [GitHub
 Projects](https://github.com/users/brettchalupa/projects/7/views/1).
 
+## API Documentation
+
+This gem uses [YARD](https://yardoc.org/) for API documentation. All public classes and methods are documented with examples and detailed descriptions.
+
+### Viewing the API Documentation
+
+To generate and view the API documentation locally:
+
+```console
+bundle exec rake yard
+```
+
+This will generate HTML documentation in the `doc/` directory. Open `doc/index.html` in your browser to view it.
+
+Alternatively, you can run a live documentation server with auto-reload:
+
+```console
+bundle exec rake yard:server
+```
+
+This starts a server at http://localhost:8808 that automatically reloads when you make changes to the code.
+
+### Online Documentation
+
+The API documentation is available online at [RubyDoc.info](https://www.rubydoc.info/gems/graphql-docs).
+
+### Documentation Coverage
+
+The codebase maintains 100% documentation coverage for all public APIs. You can check documentation statistics with:
+
+```console
+bundle exec yard stats
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

Rakefile

@@ -40,6 +40,24 @@ task :console do
   IRB.start
 end
 
+namespace :yard do
+  desc 'Generate YARD documentation'
+  task :doc do
+    sh 'bundle exec yard doc'
+  end
+
+  desc 'Run YARD documentation server'
+  task :server do
+    puts "Starting YARD server at http://localhost:8808"
+    puts "Press Ctrl+C to stop"
+    sh 'bundle exec yard server --reload --bind 0.0.0.0 --port 8808'
+  end
+end
+
+# Alias for convenience
+desc 'Generate YARD documentation'
+task yard: 'yard:doc'
+
 namespace :sample do
   desc 'Generate the sample documentation'
   task :generate do

graphql-docs.gemspec

@@ -55,4 +55,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-performance', '~> 1.15'
   spec.add_development_dependency 'webmock', '~> 2.3'
   spec.add_development_dependency 'webrick', '~> 1.7'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

lib/graphql-docs.rb

@@ -7,8 +7,69 @@
 require 'graphql-docs/parser'
 require 'graphql-docs/version'
 
+# 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|

lib/graphql-docs/configuration.rb

@@ -1,7 +1,27 @@
 # frozen_string_literal: true
 
 module GraphQLDocs
+  # Configuration module that defines default options for GraphQLDocs.
+  #
+  # All configuration options can be overridden when calling {GraphQLDocs.build}.
+  #
+  # @see GraphQLDocs.build
   module Configuration
+    # Default configuration options for GraphQLDocs.
+    #
+    # @return [Hash] Hash of default configuration values
+    #
+    # @option defaults [String] :filename (nil) Path to GraphQL schema IDL file
+    # @option defaults [String, GraphQL::Schema] :schema (nil) GraphQL schema as string or class
+    # @option defaults [Boolean] :delete_output (false) Delete output directory before generating
+    # @option defaults [String] :output_dir ('./output/') Directory for generated HTML files
+    # @option defaults [Hash] :pipeline_config Configuration for html-pipeline rendering
+    # @option defaults [Class] :renderer (GraphQLDocs::Renderer) Renderer class to use
+    # @option defaults [Boolean] :use_default_styles (true) Include default CSS styles
+    # @option defaults [String] :base_url ('') Base URL to prepend to assets and links
+    # @option defaults [Hash] :templates Paths to ERB template files for different GraphQL types
+    # @option defaults [Hash] :landing_pages Paths to landing page files for each type
+    # @option defaults [Hash] :classes Additional CSS class names for styling elements
     GRAPHQLDOCS_DEFAULTS = {
       # initialize
       filename: nil,

lib/graphql-docs/generator.rb

@@ -6,11 +6,37 @@
 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
@@ -49,6 +75,17 @@ def initialize(parsed_schema, options)
       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]
 
@@ -97,6 +134,10 @@ def generate
       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 = ''
@@ -121,6 +162,9 @@ def create_graphql_operation_pages
       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)
@@ -130,6 +174,9 @@ def create_graphql_object_pages
       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)
@@ -139,6 +186,9 @@ def create_graphql_query_pages
       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)
@@ -148,6 +198,9 @@ def create_graphql_mutation_pages
       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)
@@ -157,6 +210,9 @@ def create_graphql_interface_pages
       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)
@@ -166,6 +222,9 @@ def create_graphql_enum_pages
       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)
@@ -175,6 +234,9 @@ def create_graphql_union_pages
       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)
@@ -184,6 +246,9 @@ def create_graphql_input_object_pages
       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)
@@ -193,6 +258,9 @@ def create_graphql_scalar_pages
       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)