brainstem 1.0.0.pre.1 → 1.0.0

data/lib/brainstem/api_docs/introspectors/abstract_introspector.rb

@@ -0,0 +1,100 @@
+require 'brainstem/concerns/optional'
+
+module Brainstem
+  module ApiDocs
+    module Introspectors
+      class AbstractIntrospector
+        include Brainstem::Concerns::Optional
+
+        def valid_options
+          [ ]
+        end
+
+        # Returns a new instance of the introspector with the environment
+        # loaded, ready for introspection.
+        #
+        # @param [Hash] options arguments to pass on to the instance
+        # @return [AbstractIntrospector] the loaded instance
+        def self.with_loaded_environment(options = {})
+          new(options).tap(&:load_environment!)
+        end
+
+
+        # Override to return a collection of all controller classes.
+        #
+        # @return [Array<Class>] all controller classes to document
+        def controllers
+          raise NotImplementedError
+        end
+
+
+        # Override to return a collection of all presenter classes.
+        #
+        # @return [Array<Class>] all presenter classes to document
+        def presenters
+          raise NotImplementedError
+        end
+
+
+        # Override to return a collection of hashes with the minimum following
+        # keys:
+        #
+        #     +:path+ - the relative path (i.e. the endpoint)
+        #     +:controller+ - the managing controller
+        #     +:action+ - the managing action
+        #     +:http_method+ - an array of the HTTP methods this route is available on.
+        #
+        def routes
+          raise NotImplementedError
+        end
+
+
+        # Provides both a sanity check to ensure that output confirms to
+        # interface and also confirms that there is actually something to
+        # generate docs for.
+        #
+        # @return [Boolean] Whether the Introspector is valid
+        def valid?
+          valid_controllers? && valid_presenters? && valid_routes?
+        end
+
+
+        #######################################################################
+        private
+        #######################################################################
+
+        # Don't allow instantiation through 'new'. We want to ensure that
+        # instantiation happens through +with_loaded_environment.
+        private_class_method :new
+
+
+        # Loads the host application environment.
+        # @api private
+        def load_environment!
+          raise NotImplementedError
+        end
+
+
+        def valid_controllers?
+          controllers.is_a?(Array) &&
+            controllers.count > 0 &&
+            controllers.all? {|c| c.class == Class }
+        end
+
+        def valid_presenters?
+          presenters.is_a?(Array) &&
+            presenters.all? {|p| p.class == Class }
+        end
+
+        def valid_routes?
+          routes.is_a?(Array) &&
+            routes.count > 0 &&
+            routes.all? do |r|
+              r.is_a?(Hash) &&
+                ([:path, :controller, :action, :http_methods] - r.keys).empty?
+            end
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/introspectors/rails_introspector.rb

@@ -0,0 +1,232 @@
+require 'brainstem/api_docs/introspectors/abstract_introspector'
+require 'brainstem/api_docs/exceptions'
+
+# For 'constantize'
+require 'active_support/inflector/methods'
+
+module Brainstem
+  module ApiDocs
+    module Introspectors
+      class RailsIntrospector < AbstractIntrospector
+
+        #
+        # Loads ./config/environment.rb (by default) and eager loads all
+        # classes (otherwise +#descendants+ returns an empty set).
+        #
+        def load_environment!
+          load rails_environment_file unless env_already_loaded?
+          ::Rails.application.eager_load!
+
+          validate!
+        rescue LoadError => e
+          raise IncorrectIntrospectorForAppException,
+            "Hosting app does not appear to be a Rails app." +
+            "You may have to manually specify an Introspector (#{e.message})."
+        end
+
+
+        #
+        # Returns a list of presenters that descend from the base presenter
+        # class.
+        #
+        # @return [Array<Class>] an array of descendant classes
+        #
+        def presenters
+          base_presenter_class.constantize.descendants
+        end
+
+
+        #
+        # Returns a list of controllers that descend from the base controller
+        # class.
+        #
+        # @return [Array<Class>] an array of descendant classes
+        #
+        def controllers
+          base_controller_class.constantize.descendants
+        end
+
+
+        #
+        # Returns an array of hashes describing the endpoints of the
+        # application. See +routes_method+ for the keys of those hashes.
+        #
+        # @see #routes_method
+        #
+        # @return [Array<Hash>] each route defined on the hosting app
+        def routes
+          routes_method.call
+        end
+
+
+        #######################################################################
+        private
+        #######################################################################
+
+
+        def valid_options
+          super | [
+            :routes_method,
+            :rails_environment_file,
+            :base_presenter_class,
+            :base_controller_class,
+          ]
+        end
+
+
+        #
+        # Used to short-circuit loading if Rails is already loaded, which
+        # reduces start-up time substantially.
+        #
+        # @return [Boolean] whether Rails has already been loaded.
+        def env_already_loaded?
+          defined? Rails
+        end
+
+
+        # Returns the path of the Rails +config/environment.rb+ file - by
+        # default, +#{Dir.pwd}/config/environment.rb+.
+        #
+        # @return [String] the absolute path of the config/environment.rb file.
+        #
+        def rails_environment_file
+          @rails_environment_file ||= File.expand_path(
+            File.join(Dir.pwd, 'config', 'environment.rb')
+          )
+        end
+
+
+        #
+        # Allows a custom location to be set for the environment file if - for
+        # example - the command were to be called from a cron task that cannot
+        # change directory.
+        #
+        attr_writer :rails_environment_file
+
+
+        #
+        # Returns the name of the base presenter class.
+        #
+        # Because the initializer that contains configuration data is unlikely
+        # to have been loaded, this may also return a Proc, which will be called
+        # after the environment is loaded.
+        #
+        # @return [String,Proc] the base presenter class or a proc that returns
+        #   the same
+        #
+        def base_presenter_class
+          proc_or_string = (@base_presenter_class ||= "::Brainstem::Presenter")
+          proc_or_string.respond_to?(:call) ? proc_or_string.call : proc_or_string
+        end
+
+
+        #
+        # Allows for the specification for an alternate base presenter class
+        # if - for example - only documentation of children of +MyBasePresenter+
+        # is desired.
+        #
+        # This argument accepts a string because most classes will not be
+        # defined at the time of passing, and will only be defined after
+        # environment load.
+        #
+        # Because the initializer that contains configuration data is unlikely
+        # to have been loaded, this may also return a Proc, which will be called
+        # after the environment is loaded.
+        #
+        # @param [String,Proc] base_presenter_class the class name to use as the
+        #   base presenter, or a proc which returns the same.
+        #
+        attr_writer :base_presenter_class
+
+
+        #
+        # Returns the name of the base controller class.
+        #
+        # Because the initializer that contains configuration data is unlikely
+        # to have been loaded, this may also return a Proc, which will be called
+        # after the environment is loaded.
+        #
+        # @return [String,Proc] the base controller class or a proc that returns
+        #   the same
+        #
+        def base_controller_class
+          proc_or_string = (@base_controller_class ||= "::ApplicationController")
+          proc_or_string.respond_to?(:call) ? proc_or_string.call : proc_or_string
+        end
+
+
+        #
+        # Allows for the specification for an alternate base controller class
+        # if - for example - only documentation of children of ApiController
+        # is desired. Best used through passing an argument to
+        # +with_loaded_environment+.
+        #
+        # This argument accepts a string because most classes will not be
+        # defined at the time of passing, and will only be defined after
+        # environment load.
+        #
+        # Because the initializer that contains configuration data is unlikely
+        # to have been loaded, this may also return a Proc, which will be called
+        # after the environment is loaded.
+        #
+        # @param [String,Proc] klass the class to use as the base controller, or
+        #   a a method which returns the same.
+        #
+        attr_writer :base_controller_class
+
+
+        #
+        # Returns the proc that is called to format and retrieve routes.
+        # The proc's return must be an array of hashes that contains the
+        # following keys:
+        #
+        #     +:path+ - the relative path
+        #     +:controller+ - the managing controller as a constant
+        #     +:controller_name+ - the internal underscored name of the controller
+        #     +:action+ - the managing action
+        #     +:http_method+ - an array of the HTTP methods this route is available on.
+        #
+        def routes_method
+          @routes_method ||= Proc.new do
+            Rails.application.routes.routes.map do |route|
+              next unless route.defaults.has_key?(:controller) &&
+                controller_const = "#{route.defaults[:controller]}_controller"
+                  .classify
+                  .constantize rescue nil
+
+              {
+                alias:            route.name,
+                path:             route.path.spec.to_s,
+                controller_name:  route.defaults[:controller],
+                controller:       controller_const,
+                action:           route.defaults[:action],
+                http_methods:     route.constraints
+                  .fetch(:request_method, nil)
+                  .inspect
+                  .gsub(/[\/\$\^]/, '')
+                  .split("|")
+              }
+            end.compact
+          end
+        end
+
+
+        #
+        # Allows setting the routes method used to retrieve the routes if - for
+        # example - your application needs to retrieve additional data or if it
+        # uses an explicit routing table to define documentable endpoints.
+        #
+        attr_writer :routes_method
+
+
+        #
+        # Throws an error if the introspector did not produce valid results.
+        #
+        def validate!
+          raise InvalidIntrospectorError, "Introspector is not valid." \
+            unless valid?
+        end
+      end
+    end
+  end
+end

data/lib/brainstem/api_docs/presenter.rb

@@ -0,0 +1,225 @@
+require 'brainstem/api_docs'
+require 'brainstem/concerns/optional'
+require 'brainstem/concerns/formattable'
+require 'forwardable'
+require 'active_support/inflector'
+
+#
+# Wrapper for common presenter information lookups.
+#
+module Brainstem
+  module ApiDocs
+    class Presenter
+      extend Forwardable
+      include Concerns::Optional
+      include Concerns::Formattable
+
+
+      def valid_options
+        super | [
+          :const,
+          :target_class,
+          :filename_pattern,
+          :filename_link_pattern,
+          :document_empty_associations,
+          :document_empty_filters
+        ]
+      end
+
+      attr_accessor :const,
+                    :target_class,
+                    :document_empty_associations,
+                    :document_empty_filters
+
+      attr_writer   :filename_pattern,
+                    :filename_link_pattern
+
+      alias_method :document_empty_associations?, :document_empty_associations
+      alias_method :document_empty_filters?,      :document_empty_filters
+
+
+      def initialize(atlas, options = {})
+        self.atlas = atlas
+        self.document_empty_associations = Brainstem::ApiDocs.document_empty_presenter_associations
+        self.document_empty_filters      = Brainstem::ApiDocs.document_empty_presenter_filters
+
+        super options
+        yield self if block_given?
+      end
+
+
+      def suggested_filename(format)
+        filename_pattern
+          .gsub('{{name}}', target_class.to_s.underscore)
+          .gsub('{{extension}}', extension)
+      end
+
+
+      def suggested_filename_link(format)
+        filename_link_pattern
+          .gsub('{{name}}', target_class.to_s.underscore)
+          .gsub('{{extension}}', extension)
+      end
+
+
+      attr_accessor :atlas
+
+
+      def extension
+        @extension ||= Brainstem::ApiDocs.output_extension
+      end
+
+
+      def filename_pattern
+        @filename_pattern ||= Brainstem::ApiDocs.presenter_filename_pattern
+      end
+
+
+      def filename_link_pattern
+        @filename_link_pattern ||= Brainstem::ApiDocs.presenter_filename_link_pattern
+      end
+
+
+      delegate :configuration => :const
+      delegate :find_by_class => :atlas
+
+
+      def nodoc?
+        configuration[:nodoc]
+      end
+
+
+      def title
+        contextual_documentation(:title) || const.to_s.demodulize
+      end
+
+
+      def brainstem_keys
+        const.possible_brainstem_keys.to_a.sort
+      end
+
+
+      def description
+        contextual_documentation(:description) || ""
+      end
+
+
+      def valid_fields(fields = configuration[:fields])
+        fields.to_h.reject do |k, v|
+          if nested_field?(v)
+            valid_fields_in(v).none?
+          else
+            invalid_field?(v)
+          end
+        end
+      end
+      alias_method :valid_fields_in, :valid_fields
+
+
+      def invalid_field?(field)
+        field.options[:nodoc]
+      end
+
+
+      def nested_field?(field)
+        !field.respond_to?(:options)
+      end
+
+
+      def valid_filters
+        configuration[:filters]
+          .to_h
+          .keep_if(&method(:documentable_filter?))
+      end
+
+
+      def documentable_filter?(_, filter)
+        !filter[:nodoc] &&
+          (
+            document_empty_filters? || # document empty filters or
+            !(filter[:info] || "").empty? # has info string
+          )
+      end
+
+
+      def valid_sort_orders
+        configuration[:sort_orders].to_h.reject {|k, v| v[:nodoc] }
+      end
+
+
+      def valid_associations
+        configuration[:associations]
+          .to_h
+          .keep_if(&method(:documentable_association?))
+      end
+
+
+
+      def link_for_association(association)
+        if (associated_presenter = find_by_class(association.target_class)) &&
+            !associated_presenter.nodoc?
+          relative_path_to_presenter(associated_presenter, :markdown)
+        else
+          nil
+        end
+      end
+
+
+      #
+      # Returns whether this association should be documented based on nodoc
+      # and empty description.
+      #
+      # @return [Bool] document this association?
+      #
+      def documentable_association?(_, association)
+        !association.options[:nodoc] && # not marked nodoc and
+          (
+            document_empty_associations? || # document empty associations or
+            !(association.description.nil? || association.description.empty?) # has description
+          )
+      end
+
+
+      def conditionals
+        configuration[:conditionals]
+      end
+
+
+      def default_sort_order
+        configuration[:default_sort_order] || ""
+      end
+
+
+      def default_sort_field
+        @default_sort_field ||= (default_sort_order.split(":")[0] || nil)
+      end
+
+
+      def default_sort_direction
+        @default_sort_direction ||= (default_sort_order.split(":")[1] || nil)
+      end
+
+
+      #
+      # Returns a key if it exists and is documentable.
+      #
+      def contextual_documentation(key)
+        configuration.has_key?(key) &&
+          !configuration[key][:nodoc] &&
+          configuration[key][:info]
+      end
+
+
+      #
+      # Returns the relative path between this presenter and another given
+      # presenter.
+      #
+      def relative_path_to_presenter(presenter, format)
+        my_path        = Pathname.new(File.dirname(suggested_filename_link(format)))
+        presenter_path = Pathname.new(presenter.suggested_filename_link(format))
+
+        presenter_path.relative_path_from(my_path).to_s
+      end
+    end
+  end
+end