brainstem 1.0.0.pre.1 → 1.0.0

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

@@ -0,0 +1,73 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/markdown/helper'
+
+#
+# Responsible for formatting each endpoint.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        class EndpointCollectionFormatter < AbstractFormatter
+          include Helper
+
+          #####################################################################
+          # Public API
+          #####################################################################
+
+          def initialize(endpoint_collection, options = {})
+            self.endpoint_collection = endpoint_collection
+            self.output              = ""
+            self.zero_text           = "No endpoints were found."
+
+            super options
+          end
+
+
+          attr_accessor :endpoint_collection,
+                        :zero_text,
+                        :output
+
+
+          def valid_options
+            super | [ :zero_text ]
+          end
+
+
+          def call
+            format_endpoints!
+            format_zero_text! if output.empty?
+            output
+          end
+
+
+          #####################################################################
+          private
+          #####################################################################
+
+          def all_formatted_endpoints
+            endpoint_collection
+              .only_documentable
+              .formatted(:markdown)
+              .reject(&:empty?)
+          end
+
+
+          def format_endpoints!
+            output << all_formatted_endpoints.join(md_hr)
+          end
+
+
+          def format_zero_text!
+            output << zero_text
+          end
+        end
+      end
+    end
+  end
+end
+
+
+
+Brainstem::ApiDocs::FORMATTERS[:endpoint_collection][:markdown] = \
+  Brainstem::ApiDocs::Formatters::Markdown::EndpointCollectionFormatter.method(:call)

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

@@ -0,0 +1,169 @@
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/markdown/helper'
+require 'active_support/core_ext/hash/except'
+require 'forwardable'
+
+#
+# Responsible for formatting each endpoint.
+#
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        class EndpointFormatter < AbstractFormatter
+          include Helper
+          extend Forwardable
+
+
+          ################################################################################
+          # Public API
+          ################################################################################
+
+
+          def initialize(endpoint, options = {})
+            self.endpoint = endpoint
+            self.output   = ""
+
+            super options
+          end
+
+
+          attr_accessor :endpoint,
+                        :output
+
+
+          def call
+            return output if endpoint.nodoc?
+
+            format_title!
+            format_description!
+            format_endpoint!
+            format_params!
+            format_presents!
+
+            output
+          end
+
+
+          ################################################################################
+          private
+          ################################################################################
+
+          delegate :controller => :endpoint
+
+
+          #
+          # Formats the title as given, falling back to the humanized action
+          # name.
+          #
+          def format_title!
+            output << md_h4(endpoint.title)
+          end
+
+
+          #
+          # Formats the description if given.
+          #
+          def format_description!
+            output << md_p(endpoint.description) unless endpoint.description.empty?
+          end
+
+
+          #
+          # Formats the actual URI and stated HTTP methods.
+          #
+          def format_endpoint!
+            http_methods = endpoint.http_methods.map(&:upcase).join(" / ")
+            path = endpoint.path.gsub('(.:format)', '.json')
+            output << md_code("#{http_methods} #{path}")
+          end
+
+
+          #
+          # Formats each parameter.
+          #
+          def format_params!
+            return unless endpoint.root_param_keys.any?
+
+            output << md_h5("Valid Parameters")
+            output << md_ul do
+              endpoint.root_param_keys.inject("") do |buff, (root_param_name, child_keys)|
+                if child_keys.nil?
+                  buff += parameter_with_indent_level(
+                    root_param_name,
+                    endpoint.valid_params[root_param_name],
+                    0
+                  )
+                else
+                  text = md_inline_code(root_param_name) + "\n"
+
+                  child_keys.each do |param_name|
+                    text += parameter_with_indent_level(
+                      param_name,
+                      endpoint.valid_params[param_name],
+                      1
+                    )
+                  end
+
+                  buff << md_li(text)
+                end
+
+                buff
+              end
+            end
+          end
+
+
+          #
+          # Formats a given parameter with a variable indent level. Useful for
+          # indifferently formatting root / nested parameters.
+          #
+          # @param [String] name the param name
+          # @param [Hash] options information pertinent to the param
+          # @option [Boolean] options :legacy
+          # @option [Boolean] options :recursive
+          # @option [String,Symbol] options :only Deprecated: use +actions+
+          #   block instead
+          # @option [String] options :info the doc string for the param
+          # @param [Integer] indent how many levels the output should be
+          #   indented from normal
+          #
+          def parameter_with_indent_level(title, options = {}, indent = 0)
+            options = options.dup
+            text    = md_inline_code(title)
+
+            text += " - #{options.delete(:info)}" if options.has_key?(:info)
+
+            if options.keys.any?
+              text += "\n"
+              text += md_li("Legacy: #{options[:legacy].to_s}",       indent + 1) if options.has_key?(:legacy)
+              text += md_li("Recursive: #{options[:recursive].to_s}", indent + 1) if options.has_key?(:recursive)
+              text.chomp!
+            end
+
+            md_li(text, indent)
+          end
+
+
+          #
+          # Formats the data model for the action.
+          #
+          def format_presents!
+            if endpoint.presenter
+              output << md_h5("Data Model")
+
+              link = md_a(endpoint.presenter_title, endpoint.relative_presenter_path_from_controller(:markdown))
+              output << md_ul do
+                md_li(link)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+
+Brainstem::ApiDocs::FORMATTERS[:endpoint][:markdown] = \
+  Brainstem::ApiDocs::Formatters::Markdown::EndpointFormatter.method(:call)

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

@@ -0,0 +1,76 @@
+# This is a very simple DSL that makes generating a markdown document a bit
+# easier.
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        module Helper
+          def md_h1(text)
+            "# #{text}\n\n"
+          end
+
+
+          def md_h2(text)
+            "## #{text}\n\n"
+          end
+
+
+          def md_h3(text)
+            "### #{text}\n\n"
+          end
+
+
+          def md_h4(text)
+            "#### #{text}\n\n"
+          end
+
+
+          def md_h5(text)
+            "##### #{text}\n\n"
+          end
+
+
+          def md_strong(text)
+            "**#{text}**"
+          end
+
+
+          def md_hr
+            "-----\n\n"
+          end
+
+
+          def md_p(text)
+            text + "\n\n"
+          end
+
+
+          def md_code(text, lang = "")
+            "```#{lang}\n#{text}\n```\n\n"
+          end
+
+
+          def md_inline_code(text)
+            "`#{text}`"
+          end
+
+
+          def md_ul(&block)
+            (instance_eval(&block) || "") + "\n\n"
+          end
+
+
+          def md_li(text, indent_level = 0)
+            "#{' ' * (indent_level * 4)}- #{text}\n"
+          end
+
+
+          def md_a(text, link)
+            "[#{text}](#{link})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,200 @@
+require 'active_support/core_ext/string/inflections'
+require 'brainstem/api_docs/formatters/abstract_formatter'
+require 'brainstem/api_docs/formatters/markdown/helper'
+
+module Brainstem
+  module ApiDocs
+    module Formatters
+      module Markdown
+        class PresenterFormatter < AbstractFormatter
+          include Helper
+
+
+          def initialize(presenter, options = {})
+            self.presenter = presenter
+            self.output    = ""
+            super options
+          end
+
+
+          attr_accessor :presenter,
+                        :output
+
+
+          def call
+            return output if presenter.nodoc?
+
+            format_title!
+            format_brainstem_keys!
+            format_description!
+            format_fields!
+            format_filters!
+            format_sort_orders!
+            format_associations!
+
+            output
+          end
+
+
+          #####################################################################
+          private
+          #####################################################################
+
+          def format_title!
+            output << md_h4(presenter.title)
+          end
+
+
+          def format_brainstem_keys!
+            text = "Top-level key: "
+            text << presenter.brainstem_keys
+              .map(&method(:md_inline_code))
+              .join(" / ")
+
+            output << md_p(text)
+          end
+
+
+          def format_description!
+            output << md_p(presenter.description) unless presenter.description.empty?
+          end
+
+
+          def format_field_leaf(field, indent_level)
+            text = md_inline_code(field.name.to_s)
+            text << " (#{md_inline_code(field.type.to_s.capitalize)})"
+
+            text << "\n"
+            text << md_li(field.description, indent_level + 1) if field.description
+
+            if field.options[:if]
+              conditions = field.options[:if]
+                .reject { |cond| presenter.conditionals[cond].options[:nodoc] }
+                .map {|cond| presenter.conditionals[cond].description || "" }
+                .delete_if(&:empty?)
+                .join(" and ")
+
+              text << md_li("visible when #{conditions}", indent_level + 1) unless conditions.empty?
+            end
+
+            text << md_li("only returned when requested through the #{md_inline_code("optional_fields")} param") if field.optional?
+            text.chomp!
+          end
+
+
+          def format_field_branch(branch, indent_level = 0)
+            branch.inject("") do |buffer, (name, field)|
+              if nested_field?(field)
+                sub_fields = md_inline_code(name.to_s) + "\n"
+                sub_fields << format_field_branch(field.to_h, indent_level + 1)
+                buffer     += md_li(sub_fields, indent_level)
+              else
+                buffer += md_li(format_field_leaf(field, indent_level), indent_level)
+              end
+            end
+          end
+
+
+          def nested_field?(field)
+            !field.respond_to?(:options)
+          end
+
+
+          def format_fields!
+            output << md_h5("Fields")
+
+            if presenter.valid_fields.any?
+
+              output << md_ul do
+                format_field_branch(presenter.valid_fields)
+              end
+            else
+              output << md_p("No fields were listed.")
+            end
+          end
+
+
+          def format_filters!
+            if presenter.valid_filters.any?
+              output << md_h5("Filters")
+              output << md_ul do
+                presenter.valid_filters.inject("") do |buffer, (name, opts)|
+                  text = md_inline_code(name)
+
+                  if opts[:info]
+                    text << "\n"
+                    text << md_li(opts[:info], 1)
+                    text.chomp!
+                  end
+
+                  buffer += md_li(text)
+                end
+              end
+            end
+          end
+
+
+          def format_sort_orders!
+            if presenter.valid_sort_orders.any?
+              output << md_h5("Sort Orders")
+              output << md_ul do
+                sorted_orders = presenter.valid_sort_orders.sort_by { |name, _| name.to_s }
+
+                # Shift the default sort_order to the top
+                sorted_orders.unshift sorted_orders.delete_at(sorted_orders.index { |name, _| name.to_s == presenter.default_sort_field })
+
+                sorted_orders.inject("") do |buffer, (name, opts)|
+                  text = "#{md_inline_code(name.to_s)}"
+
+                  if presenter.default_sort_field == name.to_s
+                    text += " - #{md_strong("default")} (#{presenter.default_sort_direction})"
+                  end
+
+                  if opts[:info]
+                    text += "\n" + md_li(opts[:info], 1)
+                    text.chomp!
+                  end
+
+                  buffer += md_li(text)
+                end
+              end
+            end
+          end
+
+
+          def format_associations!
+            if presenter.valid_associations.any?
+              output << md_h5("Associations")
+
+              output << "Association Name | Associated Class | Description\n"
+              output << " --------------  |  --------------  |  ----------\n"
+
+              output << presenter.valid_associations.inject("") do |buffer, (_, association)|
+                link = presenter.link_for_association(association)
+                if link
+                  link = md_a(association.target_class, link)
+                else
+                  link = association.target_class.to_s
+                end
+
+                desc = association.description.to_s
+                if association.options && association.options[:restrict_to_only]
+                  desc += "." unless desc =~ /\.\s*\z/
+                  desc += "  Restricted to queries using the #{md_inline_code("only")} parameter."
+                  desc.strip!
+                end
+
+                buffer << md_inline_code(association.name) + " | " + link + " | " + desc + "\n"
+              end
+
+              output << "\n"
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Brainstem::ApiDocs::FORMATTERS[:presenter][:markdown] = \
+  Brainstem::ApiDocs::Formatters::Markdown::PresenterFormatter.method(:call)