Add a bunch of documentation

Author: wagenet

.gitignore

@@ -1,4 +1,6 @@
 .bundle/
+.yardoc/
+doc/
 log/*.log
 pkg/
 spec/.rspec-examples.txt

.yardext.rb

@@ -0,0 +1,17 @@
+require 'kramdown'
+require 'yard'
+
+# Make new Kramdown class with Github Formatted Markdown on
+class KramdownGFM < Kramdown::Document
+  def initialize(text, opts={})
+    super(text, opts.merge(input: 'GFM', hard_wrap: false))
+  end
+end
+
+# Register new KramdownGFM
+YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown] <<
+  { lib: :"kramdown-parser-gfm", :const => "KramdownGFM" }
+
+# Register custom templates
+YARD::Templates::Engine.register_template_path File.expand_path("yard/templates", __dir__)
+

.yardopts

@@ -0,0 +1,4 @@
+--no-private
+--load .yardext.rb
+--markup-provider=kramdown-parser-gfm
+--markup=markdown

Gemfile.lock

@@ -116,6 +116,9 @@ GEM
       activerecord
       kaminari-core (= 1.1.1)
     kaminari-core (1.1.1)
+    kramdown (2.1.0)
+    kramdown-parser-gfm (1.0.1)
+      kramdown (~> 2.0)
     loofah (2.2.3)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
@@ -168,6 +171,7 @@ GEM
     responders (2.4.0)
       actionpack (>= 4.2.0, < 5.3)
       railties (>= 4.2.0, < 5.3)
+    rouge (3.3.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -204,6 +208,7 @@ GEM
     websocket-driver (0.7.0)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.3)
+    yard (0.9.19)
 
 PLATFORMS
   ruby
@@ -214,11 +219,14 @@ DEPENDENCIES
   graphiti-rails!
   graphiti_spec_helpers (~> 1.0.1)
   kaminari
+  kramdown-parser-gfm
   pry
   pry-byebug
   responders
+  rouge
   rspec-rails
   sqlite3
+  yard
 
 BUNDLED WITH
    2.0.1

README.md

@@ -1,9 +1,9 @@
 # Graphiti::Rails
 
-Graphiti::Rails is a more robust Rails integration for Graphiti.
+Graphiti::Rails provides robust Rails integration for Graphiti, following standard Rails conventions.
 
 ## Usage
-TODO
+Out of the box, Graphiti::Rails requires no configuration!
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -13,42 +13,49 @@ gem 'graphiti-rails'
 ```
 
 ### Additional Setup
-We also recommend that you set `config.debug_exception_response_format = :api` in your `config/application.rb`.
-This will cause the [`ActionDispatch::DebugExceptions`][debug-exceptions]
-middleware to generate debug information in the requested content-type instead of as HTML only. In turn, this allows
-graphti-rails to generate more specific error messages for JSON API requests.
+We also recommend the following in `config/application.rb`:
+
+```ruby
+config.debug_exception_response_format = :api
+```
+
+This will cause the [`ActionDispatch::DebugExceptions`][debug-exceptions] middleware to generate debug information in the requested content-type instead of as HTML only. In turn, this allows graphti-rails to generate more specific error messages for JSON API requests.
 
 ## Features
 
 ### Exception Handling
-By default, Rails does a few things to handle exceptions. We integrate into this handling to ensure behavior
-as close to the Rails defaults while still adding important conventions and additional information provide by
-Graphiti.
+By default, Rails does a few things to handle exceptions. We integrate into this handling to ensure behavior as close to the Rails defaults while still adding important conventions and additional information provide by Graphiti.
 
 #### `rescue_from`
 
-At the highest level, is [`rescue_from`][rescue-from] which allows you to handle an error at the controller level.
-This bypasses all default error handling in Rails, leaving it up to the developer to account for all scenarios.
-In the future, we would like to provide some APIs for default handling in these cases.
+At the highest level, is [`rescue_from`][rescue-from] which allows you to handle an error at the controller level. This bypasses all default error handling in Rails, leaving it up to the developer to account for all scenarios. In the future, we would like to provide some APIs for default handling in these cases.
 
 #### `ActionDispatch::DebugExceptions`
 
-Next is [`ActionDispatch::DebugExceptions`][debug-exceptions]. This middleware logs exceptions and renders debugging
-information for local requests. We hook in here to log more information available from some Graphiti exceptions.
+Next is [`ActionDispatch::DebugExceptions`][debug-exceptions]. This middleware logs exceptions and renders debugging information for local requests. We hook in here to log information in a proper format for JSON:API.
 
 #### `ActionDispatch::ShowExceptions`
 
-Last is [`ActionDispatch::ShowExceptions`][show-exceptions]. This middleware rescues any exception returned by the
-application and calls an exceptions app that will wrap it in a format for the end user. We wrap the exceptions app
-to ensure that JSON API errors are always rendered in the standard format.
+Last is [`ActionDispatch::ShowExceptions`][show-exceptions]. This middleware rescues any exception returned by the application and calls an exceptions app that will wrap it in a format for the end user. We wrap the exceptions app to ensure that JSON:API errors are always rendered in the standard format.
+
+### Context Wrapping
+We wrap all requests in a Graphiti context pointing to the current controller instance. If you'd like to use a different context, overwrite the `graphiti_context` method in your controller.
+
+For more information about Graphiti context, see the [Graphiti docs][context].
+
+### Debugging
+We also provide hooks for Graphiti's built-in debugger. For more information see the [Graphiti docs][debugger].
 
 ## Contributing
-Contribution directions go here.
+We'd love to have your help improving graphiti-rails. To chat with the team and other users, join the `#rails` channel on [Slack][slack].
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 
 [debug-exceptions]: https://api.rubyonrails.org/classes/ActionDispatch/DebugExceptions.html
-[rescue-from]: (https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from)
+[context]: https://www.graphiti.dev/guides/concepts/resources#context
+[debugger]: https://www.graphiti.dev/guides/concepts/debugging#debugger
+[rescue-from]: https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from
 [show-exceptions]: https://api.rubyonrails.org/classes/ActionDispatch/ShowExceptions.html
+[slack]: https://join.slack.com/t/graphiti-api/shared_invite/enQtMjkyMTA3MDgxNTQzLWVkMDM3NTlmNTIwODY2YWFkMGNiNzUzZGMzOTY3YmNmZjBhYzIyZWZlZTk4YmI1YTI0Y2M0OTZmZGYwN2QxZjg

Rakefile

@@ -4,17 +4,11 @@ rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-require 'rdoc/task'
+require 'yard'
 require 'rspec/core/rake_task'
 require 'bundler/gem_tasks'
 
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Graphiti::Rails'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.md')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+YARD::Rake::YardocTask.new
 
 RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = "--order random"

graphiti-rails.gemspec

@@ -34,4 +34,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "kaminari"
   spec.add_development_dependency "factory_bot"
   spec.add_development_dependency "responders"
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "kramdown-parser-gfm"
+  spec.add_development_dependency "rouge"
 end

lib/graphiti/rails.rb

@@ -5,6 +5,7 @@ module Graphiti
     remove_const :Rails
   end
 
+  # Rails integration for Graphiti. See {file:README.md} for more details.
   module Rails
     # While this allow custom errors to be registered we currently don't recommend relying on this
     # functionality unless you are absolutely certain you know what you're doing. The main issue is
@@ -15,6 +16,8 @@ def self.included(_klass)
       ActiveSupport::Deprecation.warn("With graphiti-rails, including Graphiti::Rails is unnecessary")
     end
 
+    # A list of formats as symbols which will be handled by a GraphitiErrors::ExceptionHandler.
+    # Defaults to `[:jsonapi]`.
     cattr_accessor :handled_exception_formats, default: []
 
     autoload :Context, "graphiti/rails/context"
@@ -23,6 +26,9 @@ def self.included(_klass)
     autoload :DefaultExceptionHandler, "graphiti/rails/exception_handlers"
     autoload :InvalidRequestExceptionHandler, "graphiti/rails/exception_handlers"
 
+    # The default exception handler for Graphiti::Rails errors.
+    # In general, you should not need to call or modify this.
+    # @private
     def self.default_exception_handler
       DefaultExceptionHandler
     end
@@ -32,24 +38,36 @@ def self.default_exception_handler
         handler: InvalidRequestExceptionHandler
     end
 
+    # Returns a boolean of whether the specified content type should be handled by a Graphiti exception handler.
+    # The list of format can be found in `.handled_exception_formats`.
+    # @param content_type [Mime::Type]
+    # @return [Boolean]
     def self.render_exception_for_format?(content_type)
       handled_exception_formats.include?(content_type.to_sym)
     end
 
-    # TODO: Move this into GraphitiErrors
+    # @return [GraphitiErrors::ExceptionHandler]
     def self.exception_handler_for(exception)
+      # TODO: Move this into GraphitiErrors
       _errorable_registry[exception.class] || default_exception_handler.new
     end
 
-    # TODO: Move this into GraphitiErrors
+    # @param [Exception] exception
+    # @param [Boolean] show_raw_error (false)
+    # @return [Array<Integer, Hash>] HTTP status and payload
     def self.exception_details(exception, show_raw_error: false)
+      # TODO: Move this into GraphitiErrors
       exception_klass = exception_handler_for(exception)
       exception_klass.show_raw_error = show_raw_error
       status = exception_klass.status_code(exception)
       payload = exception_klass.error_payload(exception)
       [status, payload]
     end
 
+    # @param [Exception] exception
+    # @param [Mime::Type] content_type
+    # @param [Hash] keywords passed through to {.exception_details}
+    # @return [Array<Integer, Mime::Type, String>] HTTP status, content type, and payload
     def self.rendered_exception(exception, content_type:, **keywords)
       status, body = exception_details(exception, **keywords)
 

lib/graphiti/rails/action_dispatch.rb

@@ -1,33 +1,30 @@
 # The standard Rails ShowExceptions middleware passes exceptions on to `config.exceptions_app`.
-# However, the default exceptions_app (PublicExceptions) doesn't handle JSON API responses
-# correctly, so we wrap it ourselves to ensure correct handling.
-#
-# One potential problem here is if people want to handle the JSON API responses themselves.
-# In that case, we might actually want to extend PublicExceptions insteand and then let people use
-# their own handling when they overwite the exceptions app. The downside to this is that people
-# setting their own exceptions app may not know that they should handle JSON API specially.
-#
-# If we continue with this approach, we should see about getting an API into Rails for this.
-ActionDispatch::ShowExceptions.class_eval do
+# Here we wrap the specified exceptions app to handle desired content types via GraphititErrors::ExceptionHandler.
+# See {file:README.md#actiondispatchshowexceptions} for more details.
+class ActionDispatch::ShowExceptions
+  # TODO: See about adding a Rails API for this
+
+  # @private
   alias_method :initialize_without_graphiti, :initialize
+
+  # @private
   def initialize(*args)
     initialize_without_graphiti(*args)
     @exceptions_app = Graphiti::Rails::ExceptionsApp.new(@exceptions_app)
   end
 end
 
-# Since we have more information for JSON API errors from Graphiti we hijack the defaults
-# and do do the better rendering. Ideally, we'd have a hook in Rails for this.
+# Here we monkeypatch to support using GraphitiErrors::ExceptionHandler where desired.
+# See {file:README.md#actiondispatchdebugexceptions} for more details.
 #
 # Set `config.debug_exception_response_format = :api` for this to work correctly.
 #
-# TODO: Investigate whether dev tools will render a returned HTML formatted error correctly.
-# If so, there may be some benefit in not changing `debug_exception_response_format` since
-# an HTML formatted error might be nicer to read than JSON formatted. However, we should
-# still handle the JSON API case correctly when `debug_exception_response_format == :api`.
-ActionDispatch::DebugExceptions.class_eval do
+# NOTE: There may be some benefit in not changing `debug_exception_response_format` since
+# an HTML formatted error might render more nicely in browser developer tools than JSON formatted.
+class ActionDispatch::DebugExceptions
   private
 
+  # TODO: Investigate adding a Rails hook for this.
   alias_method :render_for_api_request_without_graphiti, :render_for_api_request
   def render_for_api_request(content_type, wrapper)
     if Graphiti::Rails.render_exception_for_format?(content_type)

lib/graphiti/rails/context.rb

@@ -1,21 +1,31 @@
 module Graphiti
   module Rails
+    # Wraps controller actions in a [Graphiti Context](https://www.graphiti.dev/guides/concepts/resources#context) which points to the
+    # controller instance by default.
     module Context
       def self.included(klass)
         klass.class_eval do
-          # QUESTION: Any downside to including this in all Rails controllers?
           include Graphiti::Context
           around_action :wrap_graphiti_context
         end
       end
 
-      # QUESTION: Is it fine if we wrap even non-Graphiti actions?
+      # Called by [`#around_action`](https://api.rubyonrails.org/classes/AbstractController/Callbacks/ClassMethods.html#method-i-around_action)
+      # to wrap the current action in a Graphiti context defined by {#graphiti_context}.
       def wrap_graphiti_context
-        Graphiti.with_context(jsonapi_context, action_name.to_sym) do
+        Graphiti.with_context(graphiti_context, action_name.to_sym) do
           yield
         end
       end
 
+      # The context to use for Graphiti Resources. Defaults to the controller instance.
+      # Can be redefined for different behavior.
+      def graphiti_context
+        jsonapi_context
+      end
+
+      # @private
+      # @deprecated Use {#graphiti_context} instead
       def jsonapi_context
         self
       end