brainstem 1.0.0.pre.1 → 1.0.0

data/lib/brainstem/api_docs/controller_collection.rb

@@ -0,0 +1,40 @@
+require 'brainstem/api_docs/abstract_collection'
+require 'brainstem/api_docs/controller'
+
+module Brainstem
+  module ApiDocs
+    class ControllerCollection < AbstractCollection
+
+
+      #
+      # Creates a new controller from a route object and appends it to the
+      # collection.
+      def create_from_route(route)
+        Controller.new(atlas,
+          const:  route[:controller],
+          name:   route[:controller_name].split("/").last
+        ).tap { |controller| self.<< controller }
+      end
+
+
+      #
+      # Finds a controller from a route object.
+      #
+      def find_by_route(route)
+        find do |controller|
+          controller.const == route[:controller]
+        end
+      end
+
+
+      #
+      # Finds a controller from a route object or creates one if it does not
+      # exist.
+      #
+      def find_or_create_from_route(route)
+        find_by_route(route) || create_from_route(route)
+      end
+      alias_method :find_or_create_by_route, :find_or_create_from_route
+    end
+  end
+end

data/lib/brainstem/api_docs/endpoint.rb

@@ -0,0 +1,234 @@
+require 'brainstem/concerns/optional'
+require 'active_support/core_ext/string/inflections'
+require 'brainstem/concerns/formattable'
+require 'forwardable'
+require 'pathname'
+
+#
+# Per-endpoint holder for presenter and controller information.
+#
+module Brainstem
+  module ApiDocs
+    class Endpoint
+      extend Forwardable
+      include Concerns::Optional
+      include Concerns::Formattable
+
+      ACTION_ORDER = %w(index show create update delete)
+
+      def valid_options
+        super | [
+          :path,
+          :http_methods,
+          :controller,
+          :controller_name,
+          :action,
+          :presenter
+        ]
+      end
+
+
+      def initialize(atlas, options = {})
+        self.atlas = atlas
+        super options
+        yield self if block_given?
+      end
+
+
+      attr_accessor :path,
+                    :http_methods,
+                    :controller,
+                    :controller_name,
+                    :action,
+                    :atlas
+
+
+      #
+      # Pretty prints each endpoint.
+      #
+      def to_s
+        "#{http_methods.join(" / ")} #{path}"
+      end
+
+
+      #
+      # Merges http methods (for de-duping Rails' routes).
+      #
+      def merge_http_methods!(methods)
+        self.http_methods |= methods
+      end
+
+
+      #
+      # Sorts this endpoint in comparison to other endpoints.
+      #
+      # Follows a manually defined order of precedence (+ACTION_ORDER+). The
+      # earlier an action name appears on the list, the earlier it is sorted.
+      #
+      # In the event that an action is not on the list, it is sorted after any
+      # listed routes, and then sorted alphabetically among the remainder.
+      #
+      def <=>(other)
+
+        # Any unordered routes are assigned an index of +ACTION_ORDER.count+.
+        ordered_actions_count = ACTION_ORDER.count
+        own_action_priority     = ACTION_ORDER.index(action.to_s)       || ordered_actions_count
+        other_action_priority   = ACTION_ORDER.index(other.action.to_s) || ordered_actions_count
+
+        # If the priorities are unequal (i.e. one or both are named; duplicates
+        # should not exist for named routes):
+        if own_action_priority != other_action_priority
+
+          # Flip order if this action's priority is greater than the other.
+          # other_action_priority <=> own_action_priority
+          own_action_priority <=> other_action_priority
+
+        # If the priorities are equal, i.e. both not in the list:
+        else
+
+          # Flip order if this action's name is alphabetically later.
+          action.to_s <=> other.action.to_s
+        end
+      end
+
+
+      ################################################################################
+      # Derived fields
+      ################################################################################
+
+      #
+      # Is the entire endpoint undocumentable?
+      #
+      def nodoc?
+        action_configuration[:nodoc]
+      end
+
+
+      def title
+        @title ||= contextual_documentation(:title) || action.to_s.humanize
+      end
+
+
+      def description
+        @description ||= contextual_documentation(:description) || ""
+      end
+
+
+      def valid_params
+        @valid_params ||= key_with_default_fallback(:valid_params)
+      end
+
+
+      #
+      # Returns a hash of all root-level params with values of an array of
+      # the parameters nested underneath, or +nil+ in the event they are
+      # root-level non-nested params.
+      #
+      # @return [Hash{Symbol => Array,NilClass}] root keys and the keys
+      #   nested under them, or nil if not a nested param.
+      #
+      def root_param_keys
+        @root_param_keys ||= begin
+          valid_params.to_h
+            .inject({}) do |hsh, (field_name, data)|
+              next hsh if data[:nodoc]
+
+              if data.has_key?(:root)
+                key  = data[:root].respond_to?(:call) ? data[:root].call(controller.const) : data[:root]
+                (hsh[key] ||= []) << field_name
+              else
+                hsh[field_name] = nil
+              end
+
+              hsh
+            end
+        end
+      end
+
+
+      #
+      # Retrieves the +presents+ settings.
+      #
+      def valid_presents
+        key_with_default_fallback(:presents) || {}
+      end
+
+
+      #
+      # Used to retrieve this endpoint's presenter constant.
+      #
+      def declared_presented_class
+        valid_presents.has_key?(:target_class) &&
+          !valid_presents[:nodoc] &&
+          valid_presents[:target_class]
+      end
+
+
+      #
+      # Stores the +ApiDocs::Presenter+ object associated with this endpoint.
+      #
+      attr_accessor :presenter
+
+
+      ################################################################################
+      # Configuration Helpers
+      #################################################################################
+
+      #
+      # Helper for retrieving configuration from its controller.
+      #
+      delegate :configuration => :controller
+      delegate :find_by_class => :atlas
+
+
+      #
+      # Helper for retrieving action-specific configuration from the controller.
+      #
+      def action_configuration
+        configuration[action] || {}
+      end
+
+
+      #
+      # Retrieves default action context from the controller.
+      #
+      def default_configuration
+        configuration[:_default] || {}
+      end
+
+
+      #
+      # Returns a key if it exists and is documentable
+      #
+      def contextual_documentation(key)
+        action_configuration.has_key?(key) &&
+          !action_configuration[key][:nodoc] &&
+          action_configuration[key][:info]
+      end
+
+
+      def key_with_default_fallback(key)
+        action_configuration[key] || default_configuration[key]
+      end
+
+
+      def presenter_title
+        presenter && presenter.title
+      end
+
+
+      #
+      # Returns the relative path from this endpoint's controller to this
+      # endpoint's declared presenter.
+      #
+      def relative_presenter_path_from_controller(format)
+        if presenter && controller
+          controller_path = Pathname.new(File.dirname(controller.suggested_filename_link(format)))
+          presenter_path  = Pathname.new(presenter.suggested_filename_link(format))
+
+          presenter_path.relative_path_from(controller_path).to_s
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/endpoint_collection.rb

@@ -0,0 +1,58 @@
+require 'brainstem/api_docs/abstract_collection'
+require 'brainstem/api_docs/endpoint'
+require 'brainstem/concerns/formattable'
+
+module Brainstem
+  module ApiDocs
+    class EndpointCollection < AbstractCollection
+      include Concerns::Formattable
+
+
+      def find_from_route(route)
+        find do |endpoint|
+          endpoint.path == route[:path] &&
+            endpoint.controller.const == route[:controller] &&
+            endpoint.action == route[:action]
+        end
+      end
+
+      alias_method :find_by_route, :find_from_route
+
+
+      def create_from_route(route, controller)
+        Endpoint.new(atlas) do |ep|
+          ep.path             = route[:path]
+          ep.http_methods     = route[:http_methods]
+          ep.controller       = controller
+          ep.controller_name  = route[:controller_name]
+          ep.action           = route[:action]
+        end.tap { |endpoint| self.<< endpoint }
+      end
+
+
+      def only_documentable
+        self.class.with_members(atlas, reject(&:nodoc?))
+      end
+
+
+      def with_declared_presented_class
+        self.class.with_members(atlas, reject { |m| m.declared_presented_class.nil? })
+      end
+
+
+      def sorted
+        self.class.with_members(atlas, sort)
+      end
+
+
+      def with_actions_in_controller(const)
+        self.class.with_members(atlas, reject { |m| !const.method_defined?(m.action) })
+      end
+
+
+      def sorted_with_actions_in_controller(const)
+        with_actions_in_controller(const).sorted
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/exceptions.rb

@@ -0,0 +1,8 @@
+module Brainstem
+  module ApiDocs
+    class IncorrectIntrospectorForAppException  < StandardError; end
+    class InvalidIntrospectorError              < StandardError; end
+    class InvalidAtlasError                     < StandardError; end
+    class NoSinkSpecifiedException              < StandardError; end
+  end
+end

data/lib/brainstem/api_docs/formatters/abstract_formatter.rb

@@ -0,0 +1,64 @@
+require 'brainstem/api_docs'
+require 'brainstem/api_docs/exceptions'
+require 'brainstem/concerns/optional'
+
+#
+# A formatter is fundamentally just a function that, when +#call+ed, accepts an
+# atlas and returns the whole or portion of its data in a readable format.
+#
+# There are (informally) several types of formatters, and you should select
+# among them appropriately when developing your own:
+#
+# 1. Entity
+#
+#       Turns a single data entity into its formatted version. For example, if
+#       formatting a Post object, call this formatter a
+#       +<Format>PostFormatter+.
+#
+# 2. Collection
+#
+#       Turns a collection of formatted data entities into a single unit.
+#       Usually this will involve concatenating and/or rejecting inappropriate
+#       output. For example, if you have a collection of Markdown strings from
+#       the MarkdownPostFormatter, you might want to generate the whole section
+#       of documentation by using a +MarkdownPostCollectionFormatter+.
+#
+# 3. Aggregate
+#
+#       A combination of entity and collection formatters. Knows how to turn a
+#       collection of unformatted entities into a single formatted document.
+#       Not as composable as the two used seperately, but far simpler. This
+#       should be named +MarkdownAggregatePostFormatter+.
+#
+# At the time of writing, there is no actual requirement to use these naming
+# conventions, but it is highly recommended for clarity of purpose.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      class AbstractFormatter
+        include Concerns::Optional
+
+        #
+        # Convenience class method for instantiating and calling.
+        #
+        def self.call(*args)
+          new(*args).call
+        end
+
+
+        def initialize(*args)
+          super args.last || {}
+        end
+
+
+        #
+        # Override to transform atlas data into serialized format.
+        #
+        def call
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/formatters/markdown/controller_formatter.rb

@@ -0,0 +1,76 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/markdown/helper'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        class ControllerFormatter < AbstractFormatter
+          include Helper
+
+          #
+          # Declares the options that are permissable to set on this instance.
+          #
+          def valid_options
+            super | [
+              :include_actions
+            ]
+          end
+
+
+          attr_accessor :controller,
+                        :include_actions,
+                        :output
+
+          alias_method :include_actions?, :include_actions
+
+
+          def initialize(controller, options = {})
+            self.controller      = controller
+            self.output          = ""
+            self.include_actions = false
+            super options
+          end
+
+
+          def call
+            return output if controller.nodoc?
+            format_title!
+            format_description!
+            format_actions!
+          end
+
+
+          #####################################################################
+          private
+          #####################################################################
+
+
+          def format_title!
+            output << md_h2(controller.title)
+          end
+
+
+          def format_description!
+            output << md_p(controller.description) unless controller.description.empty?
+          end
+
+
+          def format_actions!
+            return unless include_actions?
+
+            output << md_h3("Endpoints")
+
+            output << controller.valid_sorted_endpoints
+              .formatted_as(:markdown, zero_text: "No endpoints were found.")
+          end
+
+        end
+      end
+    end
+  end
+end
+
+
+Brainstem::ApiDocs::FORMATTERS[:controller][:markdown] = \
+  Brainstem::ApiDocs::Formatters::Markdown::ControllerFormatter.method(:call)