Host API docs during a release (#428)

On each tag, update the API documentation

.rdoc_options

@@ -0,0 +1,27 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- "lib/**/*.rb"
+- "README.md"
+- "CONTRIBUTING.md"
+- "CHANGELOG.md"
+charset: UTF-8
+exclude:
+format: hanna
+hyperlink_all: false
+line_numbers: false
+locale:
+locale_dir: locale
+locale_name:
+main_page:
+markup: markdown
+output: rdoc
+output_decoration: true
+page_dir:
+show_hash: false
+tab_width: 8
+template_stylesheets: []
+title: bugsnag-ruby API Documentation
+visibility: :protected
+webcvs:

.travis.yml

@@ -36,3 +36,16 @@ jobs:
   - stage: test
     env: GEMSETS="test sidekiq"
     rvm: 2.4.1
+  - stage: deploy
+    env: GEMSETS="test doc"
+    rvm: 2.4.1
+    script: bundle exec rake rdoc
+    if: tag =~ ^v[1-9]
+
+deploy:
+  provider: pages
+  local_dir: rdoc # only include the contents of the generated docs dir
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN # set in travis-ci dashboard
+  on:
+    tags: true # only deploy when tag is applied to commit

Gemfile

@@ -20,4 +20,8 @@ group :sidekiq, optional: true do
     gem 'sidekiq', '~> 5.0.4'
 end
 
+group :doc, optional: true do
+  gem 'hanna-nouveau'
+end
+
 gemspec

Rakefile

@@ -2,12 +2,13 @@
 
 require 'rdoc/task'
 RDoc::Task.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "bugsnag #{version}"
-  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('CONTRIBUTING.md')
+  rdoc.rdoc_files.include('CHANGELOG.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.options.push '-f', 'hanna'
+  rdoc.markup = 'markdown'
 end
 
 # RSpec tasks

lib/bugsnag.rb

@@ -30,7 +30,11 @@ module Bugsnag
   LOCK = Mutex.new
 
   class << self
+
+    ##
     # Configure the Bugsnag notifier application-wide settings.
+    #
+    # Yields a configuration object to use to set application settings.
     def configure
       yield(configuration) if block_given?
 
@@ -41,7 +45,10 @@ def configure
       end
     end
 
-    # Explicitly notify of an exception
+    ##
+    # Explicitly notify of an exception.
+    #
+    # Optionally accepts a block to append metadata to the yielded report.
     def notify(exception, auto_notify=false, &block)
       unless auto_notify.is_a? TrueClass or auto_notify.is_a? FalseClass
         configuration.warn("Adding metadata/severity using a hash is no longer supported, please use block syntax instead")
@@ -120,23 +127,32 @@ def notify(exception, auto_notify=false, &block)
       end
     end
 
-    # Configuration getters
+    ##
+    # Returns the client's Configuration object, or creates one if not yet created.
     def configuration
       @configuration = nil unless defined?(@configuration)
       @configuration || LOCK.synchronize { @configuration ||= Bugsnag::Configuration.new }
     end
 
-    # Session tracking
+    ##
+    # Returns the client's SessionTracker object, or creates one if not yet created.
     def session_tracker
       @session_tracker = nil unless defined?(@session_tracker)
       @session_tracker || LOCK.synchronize { @session_tracker ||= Bugsnag::SessionTracker.new}
     end
 
+    ##
+    # Starts a session.
+    #
+    # Allows Bugsnag to track error rates across releases.
     def start_session
       session_tracker.start_session
     end
 
-    # Allow access to "before notify" callbacks
+    ##
+    # Allow access to "before notify" callbacks as an array.
+    #
+    # These callbacks will be called whenever an error notification is being made.
     def before_notify_callbacks
       Bugsnag.configuration.request_data[:before_callbacks] ||= []
     end

lib/bugsnag/configuration.rb

@@ -121,40 +121,58 @@ def default_delivery_method=(delivery_method)
       @default_delivery_method = delivery_method
     end
 
+    ##
+    # Indicates whether the notifier should send a notification based on the
+    # configured release stage.
     def should_notify_release_stage?
       @release_stage.nil? || @notify_release_stages.nil? || @notify_release_stages.include?(@release_stage)
     end
 
+    ##
+    # Tests whether the configured API key is valid.
     def valid_api_key?
       !api_key.nil? && api_key =~ API_KEY_REGEX
     end
 
+    ##
+    # Returns the array of data that will be automatically attached to every
+    # error notification.
     def request_data
       Thread.current[THREAD_LOCAL_NAME] ||= {}
     end
 
+    ##
+    # Sets an entry in the array of data attached to every error notification.
     def set_request_data(key, value)
       self.request_data[key] = value
     end
 
+    ##
+    # Unsets an entry in the array of data attached to every error notification.
     def unset_request_data(key, value)
       self.request_data.delete(key)
     end
 
+    ##
+    # Clears the array of data attached to every error notification.
     def clear_request_data
       Thread.current[THREAD_LOCAL_NAME] = nil
     end
 
+    ##
+    # Logs an info level message
     def info(message)
       logger.info(message)
     end
 
-    # Warning logger
+    ##
+    # Logs a warning level message
     def warn(message)
       logger.warn(message)
     end
 
-    # Debug logger
+    ##
+    # Logs a debug level message
     def debug(message)
       logger.debug(message)
     end

lib/bugsnag/delivery.rb

@@ -1,18 +1,22 @@
 module Bugsnag
   module Delivery
     class << self
+      ##
       # Add a delivery method to the list of supported methods. Any registered
       # method can then be used by name in Configuration.
       #
+      # ```
       # require 'bugsnag'
       # Bugsnag::Delivery.register(:my_delivery_queue, MyDeliveryQueue)
       # Bugsnag.configure do |config|
       #   config.delivery_method = :my_delivery_queue
       # end
+      # ```
       def register(name, delivery_method)
         delivery_methods[name.to_sym] = delivery_method
       end
 
+      ##
       # Reference a delivery method by name
       def [](name)
         delivery_methods[name.to_sym]

lib/bugsnag/delivery/synchronous.rb

@@ -5,6 +5,8 @@ module Bugsnag
   module Delivery
     class Synchronous
       class << self
+        ##
+        # Attempts to deliver a payload to the given endpoint synchronously.
         def deliver(url, body, configuration, options={})
           begin
             response = request(url, body, configuration, options)

lib/bugsnag/delivery/thread_queue.rb

@@ -8,6 +8,9 @@ class ThreadQueue < Synchronous
       MUTEX = Mutex.new
 
       class << self
+
+        ##
+        # Queues a given payload to be delivered asynchronously.
         def deliver(url, body, configuration, options={})
           @configuration = configuration
 

lib/bugsnag/helpers.rb

@@ -10,6 +10,7 @@ module Helpers
     MAX_ARRAY_LENGTH = 40
     RAW_DATA_TYPES = [Numeric, TrueClass, FalseClass]
 
+    ##
     # Trim the size of value if the serialized JSON value is longer than is
     # accepted by Bugsnag
     def self.trim_if_needed(value)
@@ -23,6 +24,10 @@ def self.trim_if_needed(value)
       remove_metadata_from_events(reduced_value)
     end
 
+    ##
+    # Merges r_hash into l_hash recursively, favouring the values in r_hash.
+    #
+    # Returns a new array consisting of the merged values
     def self.deep_merge(l_hash, r_hash)
       l_hash.merge(r_hash) do |key, l_val, r_val|
         if l_val.is_a?(Hash) && r_val.is_a?(Hash)
@@ -35,6 +40,10 @@ def self.deep_merge(l_hash, r_hash)
       end
     end
 
+    ##
+    # Merges r_hash into l_hash recursively, favouring the values in r_hash.
+    #
+    # Overwrites the values in the existing l_hash
     def self.deep_merge!(l_hash, r_hash)
       l_hash.merge!(r_hash) do |key, l_val, r_val|
         if l_val.is_a?(Hash) && r_val.is_a?(Hash)
@@ -51,6 +60,7 @@ def self.deep_merge!(l_hash, r_hash)
 
     TRUNCATION_INFO = '[TRUNCATED]'
 
+    ##
     # Check if a value is a raw type which should not be trimmed, truncated
     # or converted to a string
     def self.is_json_raw_type?(value)

lib/bugsnag/integrations/mailman.rb

@@ -1,6 +1,8 @@
 require 'mailman'
 
 module Bugsnag
+  ##
+  # Extracts and appends mailman message information to error reports
   class Mailman
 
     FRAMEWORK_ATTRIBUTES = {
@@ -12,6 +14,8 @@ def initialize
       Bugsnag.configuration.app_type = "mailman"
     end
 
+    ##
+    # Calls the mailman middleware.
     def call(mail)
       begin
         Bugsnag.configuration.set_request_data :mailman_msg, mail.to_s

lib/bugsnag/integrations/rack.rb

@@ -1,4 +1,6 @@
 module Bugsnag
+  ##
+  # Automatically captures and adds Rack request information to error reports
   class Rack
 
     FRAMEWORK_ATTRIBUTES = {
@@ -31,6 +33,8 @@ def initialize(app)
       end
     end
 
+    ##
+    # Wraps a call to the application with error capturing
     def call(env)
       # Set the request data for bugsnag middleware to use
       Bugsnag.configuration.set_request_data(:rack_env, env)

lib/bugsnag/integrations/rake.rb

@@ -8,6 +8,8 @@ class Rake::Task
     :framework => "Rake"
   }
 
+  ##
+  # Executes the rake task with Bugsnag setup with contextual data.
   def execute_with_bugsnag(args=nil)
     Bugsnag.configuration.app_type ||= "rake"
     old_task = Bugsnag.configuration.request_data[:bugsnag_running_task]

lib/bugsnag/integrations/resque.rb

@@ -8,11 +8,15 @@ class Resque < ::Resque::Failure::Base
       :framework => "Resque"
     }
 
+    ##
+    # Callthrough to Bugsnag configuration.
     def self.configure(&block)
       add_failure_backend
       Bugsnag.configure(&block)
     end
 
+    ##
+    # Sets up the Resque failure backend.
     def self.add_failure_backend
       return if ::Resque::Failure.backend == self
 
@@ -30,6 +34,8 @@ def self.add_failure_backend
       end
     end
 
+    ##
+    # Notifies Bugsnag of a raised exception.
     def save
       Bugsnag.notify(exception, true) do |report|
         report.severity = "error"

lib/bugsnag/integrations/shoryuken.rb

@@ -1,6 +1,8 @@
 require 'shoryuken'
 
 module Bugsnag
+  ##
+  # Extracts and attaches Shoryuken queue information to an error report
   class Shoryuken
 
     FRAMEWORK_ATTRIBUTES = {

lib/bugsnag/integrations/sidekiq.rb

@@ -1,6 +1,8 @@
 require 'sidekiq'
 
 module Bugsnag
+  ##
+  # Extracts and attaches Sidekiq job and queue information to an error report
   class Sidekiq
 
     FRAMEWORK_ATTRIBUTES = {

lib/bugsnag/middleware/callbacks.rb

@@ -1,5 +1,8 @@
 module Bugsnag::Middleware
+  ##
+  # Calls all configured callbacks passing an error report
   class Callbacks
+
     def initialize(bugsnag)
       @bugsnag = bugsnag
     end

lib/bugsnag/middleware/classify_error.rb

@@ -1,4 +1,6 @@
 module Bugsnag::Middleware
+  ##
+  # Sets the severity to info for low-importance errors
   class ClassifyError
     INFO_CLASSES = [
         "AbstractController::ActionNotFound",

lib/bugsnag/middleware/clearance_user.rb

@@ -1,4 +1,6 @@
 module Bugsnag::Middleware
+  ##
+  # Extracts and appends clearance user information
   class ClearanceUser
     COMMON_USER_FIELDS = [:email, :name, :first_name, :last_name, :created_at, :id]
 

lib/bugsnag/middleware/exception_meta_data.rb

@@ -1,4 +1,6 @@
 module Bugsnag::Middleware
+  ##
+  # Extracts data from the exception.
   class ExceptionMetaData
     def initialize(bugsnag)
       @bugsnag = bugsnag

lib/bugsnag/middleware/ignore_error_class.rb

@@ -1,5 +1,9 @@
 module Bugsnag::Middleware
+  ##
+  # Determines if the exception should be ignored based on the configured
+  # `ignore_classes`
   class IgnoreErrorClass
+
     def initialize(bugsnag)
       @bugsnag = bugsnag
     end