betterdocs 0.2.0

data/lib/betterdocs/generator/markdown/templates/README.md.erb

@@ -0,0 +1,9 @@
+The <%= project_name %> API
+===========================
+
+API ready for use
+-----------------
+
+<%- for secion in sections >
+- [<%=section.name.to_s.camelcase](<%= section(section.name) %>.md)
+

data/lib/betterdocs/generator/markdown/templates/section.md.erb

@@ -0,0 +1,132 @@
+<%- for action in section -%>
+
+# <%= action.title %>
+
+```Rebol
+<%= action.request %>
+```
+
+<%= action.description %>
+
+## URL Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Example</th>
+    <th>Required</th>
+    <th>Description</th>
+  </tr>
+<%- for param in action.params.values -%>
+  <tr>
+    <th align="left"><%= param.name %></th>
+    <td><code><%= param.value %></code></td>
+    <td><%= param.required ? 'yes' : 'no' %></td>
+    <td><%= param.description %></td>
+  </tr>
+<%- end -%>
+</table>
+
+<%- if json_params = action.json_params.full? -%>
+## JSON Parameters
+
+JSON parameters have to be provided in the body of the request with the
+Content-Type header set to "application/json". The parameters are part of a
+flat JSON document without any nesting. Some parameters are required, others
+are optional.
+
+### Example
+
+```json
+<%= action.json_params_example_json %>
+```
+
+### Supported Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Example</th>
+    <th>Types</th>
+    <th>Required</th>
+    <th>Description</th>
+  </tr>
+  <%- for param in action.json_params.values -%>
+  <tr>
+    <th align="left"><%= param.name %></th>
+    <td><code><%= param.value %></code></td>
+    <td><%= param.types * ?| -%></td>
+    <td><%= param.required ? 'yes' : 'no' %></td>
+    <td><%= param.description %></td>
+  </tr>
+  <%- end -%>
+</table>
+<%- end -%>
+
+## Response Attributes
+
+<%- if properties = action.response.full?(:properties) -%>
+  <%- for (representer, properties) in properties.group_by(&:nesting_name) -%>
+    <%- if properties.first.nesting_name.blank? -%>
+### Root Attributes
+    <%- else -%>
+### <a id="<%= nn = properties.first.nesting_name %>" href="#<%= "#{nn}-ref" %>">↑Nested Attributes: <%= nn %></a>
+    <%- end -%>
+
+  <table>
+    <tr>
+      <th>Attribute</th>
+      <th>Types</th>
+      <th>Example</th>
+      <th>Description</th>
+    </tr>
+    <%- for property in properties -%>
+    <tr>
+      <%- if r = property.sub_representer? and r.docs.properties.full? -%>
+        <th align="left" style="white-space: nowrap">
+          <a id="<%= fn = property.full_name; "#{fn}-ref" %>" href="#<%= fn %>">
+            ↓<%= property.full_name %>
+          </a>
+        </th>
+      <%- else -%>
+      <th align="left"><%= property.full_name %></th>
+      <%- end -%>
+      <td><%= property.types * ' &#124; ' %></td>
+      <td><%= property.example %></td>
+      <td><%= property.description %></td>
+    </tr>
+    <%- end -%>
+  </table>
+  <%- end -%>
+<%- else -%>
+  <th colspan="4">No response example defined</th>
+<%- end -%>
+</table>
+
+## Response Links
+
+<table>
+  <tr>
+    <th>Linkname</th>
+    <th>Description</th>
+  </tr>
+
+<%- if links = action.response.full?(:links) -%>
+  <%- for link in links.group_by(&:nesting_name).values.reduce(&:concat) -%>
+    <tr>
+      <th align="left"><%= link.full_name %></th>
+      <td><%= link.description %></td>
+    </tr>
+  <%- end -%>
+<%- else -%>
+  <th colspan="2">No response example defined</th>
+<%- end -%>
+</table>
+
+## Response Example
+
+```json
+<%= JSON.pretty_generate(action.response) %>
+```
+
+<%- end -%>

data/lib/betterdocs/global.rb

@@ -0,0 +1,143 @@
+module Betterdocs
+  module Global
+    class << self
+      extend Tins::DSLAccessor
+
+      dsl_accessor :project_name,        'Project'         # Name of the project
+
+      dsl_accessor :api_prefix,          'api'             # Prefix that denotes the api namespace in URLs
+
+      dsl_accessor :api_controllers do
+        Dir[Rails.root.join("app/controllers/#{api_prefix}/**/*_controller.rb")]
+      end
+
+      dsl_accessor :platform_protocol,   'http'               # Not used atm
+
+      dsl_accessor :platform_host,       'localhost:3000'     # Actually host with port, but rails seems to be confused about the concept
+
+      dsl_accessor :api_protocol do platform_protocol end     # Protocol the API understands
+
+      dsl_accessor :api_host   do platform_host end           # Hostname of the API (eventuallly with port number)
+
+      dsl_accessor :asset_protocol do platform_protocol end   # Reserved
+
+      dsl_accessor :asset_host do platform_host end           # Rails asset host
+
+      dsl_accessor :api_default_format,  'json'
+
+      def api_base_url
+        "#{api_protocol}://#{api_host}/#{api_prefix}"
+      end
+
+      dsl_accessor :api_url_options do
+        { protocol: api_protocol, host: api_host, format: api_default_format }
+      end
+
+      dsl_accessor :templates_directory                     # Template directory, where customised templates live if any exist
+
+      dsl_accessor :output_directory,    'api_docs'         # Output directory, where the api docs are created
+
+      dsl_accessor :publish_git                             # URL to the git repo to which the docs are pushed
+
+      dsl_accessor :ignore do [] end                        # All lines of the .gitignore file as an array
+
+      def assets
+        @assets ||= {}
+      end
+      private :assets
+
+      # Defines an asset for the file at +path+. If +to+ was given it will be
+      # copied to this path (it includes the basename) below
+      # +templates_directory+ in the output, otherwise it will be copied
+      # directly to +templates_directory+.
+      def asset(path, to: :root)
+        if destination = to.ask_and_send(:to_str)
+          assets[path.to_s] = destination
+        elsif to == :root
+          assets[path.to_s] = to
+        else
+          raise ArgumentError, "keyword argument to needs to be a string or :root"
+        end
+      end
+
+      # Maps the assets original source path to its destination path in the
+      # output by yielding to every asset's source/destination pair.
+      def each_asset
+        for path in assets.keys
+          path = path.to_s
+          if destination = assets[path]
+            if destination == :root && output_directory
+              yield path, File.join(output_directory.to_s, File.basename(path))
+            else
+              yield path, File.join(output_directory.to_s, destination.to_str)
+            end
+          end
+        end
+      end
+
+      def configure(&block)
+        instance_eval(&block)
+        self
+      end
+
+      def config
+        if block_given?
+          yield self
+        else
+          self
+        end
+      end
+
+      def all_docs
+        Dir[api_prefix.to_s + '/**/*_controller.rb'].each_with_object([]) do |cf, all|
+          controller_name = cf.sub(/\.rb$/, '').camelcase
+          controller =
+            begin
+              controller_name.constantize
+            rescue NameError => e
+              STDERR.puts "Skipping #{cf.inspect}, #{e.class}: #{e}"
+              next
+            end
+          if docs = controller.ask_and_send(:docs)
+            all << docs
+          else
+            STDERR.puts "Skipping #{cf.inspect}, #{controller_name.inspect} doesn't respond to :docs method"
+          end
+        end
+      end
+
+      def actions
+        all_docs.reduce([]) { |a, d| a.concat(d.actions) }
+      end
+
+      def sections
+        @sections and return @sections
+        Dir.chdir Rails.root.join('app/controllers') do
+          actions.each_with_object(@sections = {}) do |action, sections|
+            sections[action.section] ||= Section.new(action.section)
+            sections[action.section] << action
+          end
+        end
+        @sections.freeze
+      end
+
+      def sections_clear
+        @sections = nil
+        self
+      end
+
+      def section(name)
+        sections[name] if sections.key?(name)
+      end
+
+      def url_helpers
+        Betterdocs.rails.application.routes.url_helpers
+      end
+
+      def url_for(options = {})
+        Betterdocs.rails.application.routes.url_for(
+          options | Betterdocs::Global.config.api_url_options)
+      end
+    end
+  end
+end

data/lib/betterdocs/json_params_representer.rb

@@ -0,0 +1,37 @@
+module Betterdocs::JsonParamsRepresenter
+  extend ActiveSupport::Concern
+  include Betterdocs::Representer
+
+  module ClassMethods
+    def build_result_object
+      ActionController::Parameters.new
+    end
+
+    def hashify(object)
+      super do |result|
+        assign_params result, object
+      end
+    end
+
+    def docs
+      @docs ||= Betterdocs::JsonParamsRepresenterCollector.new
+    end
+
+    def assign_params(result, object)
+      for param in params
+        param.assign(result, object)
+      end
+    end
+    private :assign_params
+
+    def params
+      @params ||= Set.new
+    end
+
+    def param(name, **options, &block)
+      d = doc(:param, name, **options, &block) and
+        params << d
+      self
+    end
+  end
+end

data/lib/betterdocs/json_params_representer_collector.rb

@@ -0,0 +1,48 @@
+module Betterdocs
+  class JsonParamsRepresenterCollector
+    def initialize
+      @params = {}
+    end
+
+    attr_reader :params
+
+    def param(param_name)
+      param_name = param_name.to_sym
+      @params[param_name]
+    end
+
+    def add_element(representer, type, name, **options, &block)
+      element = build_element(representer, type, name, options, &block)
+      element.add_to_collector(self)
+    end
+
+    def representer
+      @params.values.find { |v|
+        v.representer and break v.representer
+      }
+    end
+
+    def to_s
+      result = "*** #{representer} ***\n"
+      if params = @params.values.full?
+        result << "\nProperties:"
+        params.each_with_object(result) do |param, r|
+          r << "\n#{param.full_name}: (#{param.types * '|'}): #{param.description}\n"
+        end
+      end
+      result
+    end
+
+    private
+
+    def build_element(representer, type, *args, &block)
+      begin
+        element = Dsl::JsonParams.const_get(type.to_s.camelcase)
+      rescue NameError => e
+        raise ArgumentError, "unknown documentation element type #{type.inspect}"
+      end
+      element.new(representer, *args, &block)
+    end
+  end
+end
+

data/lib/betterdocs/mix_into_controller.rb

@@ -0,0 +1,19 @@
+module Betterdocs
+  module MixIntoController
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def method_added(name)
+        docs.configure_current_element(name)
+      end
+
+      def doc(type, &block)
+        docs.add_element(self, type, &block)
+      end
+
+      def docs
+        @docs ||= ControllerCollector.new
+      end
+    end
+  end
+end

data/lib/betterdocs/rake_tasks.rb

@@ -0,0 +1,5 @@
+class RakeTasks < Rails::Railtie
+  rake_tasks do
+    Dir[File.join(File.dirname(__FILE__), 'tasks/*.rake')].each { |f| load f }
+  end
+end

data/lib/betterdocs/representer.rb

@@ -0,0 +1,42 @@
+require 'action_controller'
+
+module Betterdocs::Representer
+  extend ActiveSupport::Concern
+
+  def as_json(*)
+    singleton_class.ancestors.find do |c|
+      c != singleton_class && c < Betterdocs::Representer
+    end.hashify(self)
+  end
+
+  def to_json(*a)
+    JSON::generate(as_json, *a)
+  end
+
+  module ClassMethods
+    def apply(object)
+      object.extend self
+    end
+
+    def build_result_object
+      {}
+    end
+
+    def hashify(object, &block)
+      apply(object)
+      result = build_result_object
+      instance_exec(result, &block)
+      result
+    end
+
+    def doc(type, name, **options, &block)
+      docs.add_element(self, type, name, options, &block)
+    end
+
+    def object_name(*) end
+
+    def docs
+      raise NotImplementedError, 'has to be implemented in including module'
+    end
+  end
+end

data/lib/betterdocs/result_representer.rb

@@ -0,0 +1,68 @@
+require 'set'
+require 'betterdocs/representer'
+
+module Betterdocs::ResultRepresenter
+  extend ActiveSupport::Concern
+  include Betterdocs::Dsl::Common
+  include Betterdocs::Representer
+
+  module ClassMethods
+    def hashify(object)
+      super do |result|
+        assign_properties result, object
+        assign_links      result, object
+      end
+    end
+    def doc(type, name, **options, &block)
+      docs.add_element(self, type, name, options, &block)
+    end
+
+    def docs
+      @docs ||= Betterdocs::ResultRepresenterCollector.new
+    end
+
+    def assign_links(result, object)
+      result['links'] = []
+      for link in links
+        link.assign(result, object)
+      end
+    end
+    private :assign_links
+
+    def assign_properties(result, object)
+      for property in properties
+        property.assign(result, object)
+      end
+    end
+    private :assign_properties
+
+    def properties
+      @properties ||= Set.new
+    end
+
+    def property(name, **options, &block)
+      d = doc(:property, name, **options, &block) and
+        properties << d
+      self
+    end
+
+    def collection(name, **options, &block)
+      d = doc(:collection_property, name, **options, &block) and
+        properties << d
+      self
+    end
+
+    def links
+      @links ||= Set.new
+    end
+
+    def link(name, **options, &block)
+      d = doc(:link, name, **options, &block) and links << d
+      self
+    end
+
+    def api_url_for(options = {})
+      Betterdocs::Global.url_for(options)
+    end
+  end
+end