betterdocs 0.2.0

data/lib/betterdocs/dsl/controller/action/param.rb

@@ -0,0 +1,25 @@
+class Betterdocs::Dsl::Controller::Action::Param
+  extend Tins::DSLAccessor
+  include ::Betterdocs::Dsl::Common
+
+  def initialize(param_name, &block)
+    name param_name
+    block and instance_eval(&block)
+  end
+
+  dsl_accessor :name
+
+  dsl_accessor :value
+
+  dsl_accessor :required, true
+
+  dsl_accessor :description, 'TODO'
+
+  dsl_accessor :use_in_url, true
+
+  alias use_in_url? use_in_url
+
+  def to_s
+    value
+  end
+end

data/lib/betterdocs/dsl/controller/action/response.rb

@@ -0,0 +1,47 @@
+class Betterdocs::Dsl::Controller::Action::Response
+  include Betterdocs::Dsl::Common
+  extend Tins::DSLAccessor
+
+  def initialize(name = :default, &block)
+    @name = name.to_sym
+    @data_block = block || proc {}
+  end
+
+  dsl_accessor :name
+
+  def params
+    -> name { param(name).full?(:value) }
+  end
+
+  def data
+    @data ||= instance_eval(&@data_block)
+  end
+
+  def properties
+    representer.full? { |r| r.docs.nested_properties }  || []
+  end
+
+  def links
+    representer.full? { |r| r.docs.nested_links }  || []
+  end
+
+  def representer
+    if data
+      data.ask_and_send(:representer) ||
+        data.singleton_class.ancestors.find { |c|
+        Betterdocs::ResultRepresenter >= c && c.respond_to?(:docs)
+        # Actually it's more like
+        #   Betterdocs::ResultRepresenter >= c && !c.singleton_class?
+        # in newer rubies.
+        # But singleton_class? is broken and private in ruby 2.1.x not
+        # existant in <= ruby 2.0.x and finally works in ruby 2.2.x.
+        # What a mess!
+      }
+    end
+  end
+
+  def to_json(*a)
+    my_data = data.ask_and_send(:to_hash) || data
+    my_data.to_json(*a)
+  end
+end

data/lib/betterdocs/dsl/controller/controller.rb

@@ -0,0 +1,31 @@
+require 'betterdocs/dsl/controller/controller_base'
+
+class Betterdocs::Dsl::Controller::Controller < Betterdocs::Dsl::Controller::ControllerBase
+  def name
+    @name ||= controller.to_s.underscore.sub(/_controller\z/, '').to_sym
+  end
+
+  dsl_accessor :section
+
+  dsl_accessor :description, 'TODO'
+
+  def url
+    Betterdocs::Global.url_for(
+      controller: name,
+      action: :index,
+      format: 'json'
+    )
+  end
+
+  def url_helpers
+    Betterdocs::Global.url_helpers
+  end
+
+  def to_s
+    [ controller, '', "url: #{url}", '', description, '' ] * "\n"
+  end
+
+  def add_to_collector(collector)
+    collector.controller = self
+  end
+end

data/lib/betterdocs/dsl/controller/controller_base.rb

@@ -0,0 +1,21 @@
+require 'betterdocs/dsl/common'
+
+class Betterdocs::Dsl::Controller::ControllerBase
+  include Betterdocs::Dsl::Common
+
+  def self.inherited(klass)
+    klass.class_eval { extend Tins::DSLAccessor }
+  end
+
+  def initialize(controller, &block)
+    controller(controller)
+    set_context controller
+    instance_eval(&block)
+  end
+
+  dsl_accessor :controller
+
+  def add_to_collector(collector)
+    raise NotImplementedError, 'add_to_collector needs to be implemented in subclass'
+  end
+end

data/lib/betterdocs/dsl/json_params.rb

@@ -0,0 +1,8 @@
+module Betterdocs
+  module Dsl
+    module JsonParams
+    end
+  end
+end
+
+require 'betterdocs/dsl/json_params/param'

data/lib/betterdocs/dsl/json_params/param.rb

@@ -0,0 +1,31 @@
+class Betterdocs::Dsl::JsonParams::Param < Betterdocs::Dsl::Representer
+  extend Tins::DSLAccessor
+  include Betterdocs::Dsl::Common
+  include Betterdocs::Dsl::Naming
+
+  dsl_accessor :description, 'TODO'
+
+  dsl_accessor :value, 'TODO'
+
+  dsl_accessor :types do [] end
+
+  dsl_accessor :required, true
+
+  def initialize(representer, name, options, &block)
+    super
+    types Betterdocs::Dsl::JsonTypeMapper.map_types(types)
+  end
+
+  def assign(result, object)
+    assign?(object) or return
+    result[name] = compute_value(object)
+  end
+
+  def compute_value(object)
+    object.__send__(name)
+  end
+
+  def add_to_collector(collector)
+    collector.params[name] = self
+  end
+end

data/lib/betterdocs/dsl/json_type_mapper.rb

@@ -0,0 +1,27 @@
+module Betterdocs::Dsl::JsonTypeMapper
+  module_function
+
+  def derive_json_type_from(klass)
+    Class === klass or klass = klass.class
+    result = {
+      TrueClass  => 'boolean',
+      FalseClass => 'boolean',
+      NilClass   => 'null',
+      Numeric    => 'number',
+      Array      => 'array',
+      Hash       => 'object',
+      String     => 'string',
+    }.find { |match_class, json_type|
+      match_class >= klass and break json_type
+    } || 'undefined'
+  end
+
+  def map_types(types)
+    if Array === types and types.empty?
+      types = [ types ]
+    else
+      types = Array(types)
+    end
+    types.map { |t| derive_json_type_from(t) }.uniq.sort
+  end
+end

data/lib/betterdocs/dsl/naming.rb

@@ -0,0 +1,32 @@
+module Betterdocs::Dsl::Naming
+  def initialize(*)
+    super
+    @options ||= {}
+    @below_path = []
+  end
+
+  attr_reader :options
+
+  def path
+    @below_path + [ public_name ]
+  end
+
+  def below_path(path)
+    dup.instance_eval do
+      @below_path = path
+      self
+    end
+  end
+
+  def public_name
+    @options[:as] || name
+  end
+
+  def full_name
+    path * '.'
+  end
+
+  def nesting_name
+    @below_path * '.'
+  end
+end

data/lib/betterdocs/dsl/representer.rb

@@ -0,0 +1,29 @@
+class Betterdocs::Dsl::Representer
+  def initialize(representer, name, options, &block)
+    set_context @representer = representer
+    @name = name.to_sym
+    @options = options | {
+      if:      -> { true },
+      unless:  -> { false },
+    }
+    block and instance_eval(&block)
+  end
+
+  attr_reader :name
+
+  attr_reader :representer
+
+  def assign?(object)
+    object.instance_exec(&@options[:if]) &&
+      !object.instance_exec(&@options[:unless])
+  end
+
+  def assign(result, object)
+    raise NotImplementedError, 'assign needs to be implemented in subclass'
+  end
+
+  def add_to_collector(collector)
+    raise NotImplementedError, 'add_to_collector needs to be implemented in subclass'
+  end
+end
+

data/lib/betterdocs/dsl/result.rb

@@ -0,0 +1,10 @@
+module Betterdocs
+  module Dsl
+    module Result
+    end
+  end
+end
+
+require 'betterdocs/dsl/result/property'
+require 'betterdocs/dsl/result/collection_property'
+require 'betterdocs/dsl/result/link'

data/lib/betterdocs/dsl/result/collection_property.rb

@@ -0,0 +1,9 @@
+require 'betterdocs/dsl/result/property'
+
+class Betterdocs::Dsl::Result::CollectionProperty < Betterdocs::Dsl::Result::Property
+  def compute_value(object)
+    object.__send__(name).to_a.compact.map do |v|
+      represent_with.hashify(v)
+    end
+  end
+end

data/lib/betterdocs/dsl/result/link.rb

@@ -0,0 +1,37 @@
+require 'betterdocs/dsl/representer'
+require 'betterdocs/dsl/common'
+require 'betterdocs/dsl/naming'
+
+class Betterdocs::Dsl::Result::Link < Betterdocs::Dsl::Representer
+  extend Tins::DSLAccessor
+  include Betterdocs::Dsl::Common
+  include Betterdocs::Dsl::Naming
+
+  dsl_accessor :description, 'TODO'
+
+  dsl_accessor :templated, false
+
+  def url(&block)
+    if block
+      @url = block
+    elsif @url
+      @url
+    else
+      raise ArgumentError, 'link requires an URL'
+    end
+  end
+
+  def assign(result, object)
+    assign?(object) or return
+    link = {
+      'rel'  => name.to_s,
+      'href' => object.instance_eval(&url).to_s,
+    }
+    templated and link['templated'] = true
+    result['links'].push(link)
+  end
+
+  def add_to_collector(collector)
+    collector.links[name] = self
+  end
+end

data/lib/betterdocs/dsl/result/property.rb

@@ -0,0 +1,53 @@
+require 'betterdocs/dsl/representer'
+require 'betterdocs/dsl/common'
+require 'betterdocs/dsl/naming'
+require 'betterdocs/dsl/json_type_mapper'
+
+class Betterdocs::Dsl::Result::Property < Betterdocs::Dsl::Representer
+  extend Tins::DSLAccessor
+  include Betterdocs::Dsl::Common
+  include Betterdocs::Dsl::Naming
+
+  dsl_accessor :represent_with
+
+  dsl_accessor :description, 'TODO'
+
+  dsl_accessor :example, 'TODO'
+
+  dsl_accessor :types do [] end
+
+  def initialize(representer, name, options, &block)
+    super
+    types Betterdocs::Dsl::JsonTypeMapper.map_types(types)
+    if sr = sub_representer?
+      sr < Betterdocs::ResultRepresenter or
+        raise TypeError, "#{sr.inspect} is not a Betterdocs::Result subclass"
+    end
+  end
+
+  def sub_representer?
+    represent_with
+  end
+
+  def actual_property_name
+    (options[:as] || name).to_s
+  end
+
+  def assign(result, object)
+    assign?(object) or return
+    result[actual_property_name] = compute_value(object)
+  end
+
+  def compute_value(object)
+    value = object.__send__(name)
+    if !value.nil? && represent_with
+      represent_with.hashify(value)
+    else
+      value
+    end
+  end
+
+  def add_to_collector(collector)
+    collector.properties[name] = self
+  end
+end

data/lib/betterdocs/generator/config_shortcuts.rb

@@ -0,0 +1,28 @@
+module Betterdocs
+  module Generator
+    module ConfigShortcuts
+      def config
+        Betterdocs::Global.config
+      end
+
+      def project_name
+        config.project_name
+      end
+
+      def sections
+        Dir[config.api_controllers.to_s].each(&method(:load))
+        config.sections
+      end
+
+      def section(name)
+        name = name.to_sym
+        config.section(name) or STDERR.puts "Section #{name.inspect} does not exist: Link in readme file won't work."
+        "sections/#{name}"
+      end
+
+      def api_base_url
+        config
+      end
+    end
+  end
+end

data/lib/betterdocs/generator/markdown.rb

@@ -0,0 +1,151 @@
+module Betterdocs
+  module Generator
+    class Markdown
+      include ::Betterdocs::Generator::ConfigShortcuts
+      require 'fileutils'
+      include FileUtils::Verbose
+      require 'term/ansicolor'
+      include Term::ANSIColor
+
+      def initialize(only: nil)
+        only and @only = Regexp.new(only)
+      end
+
+      def generate
+        if dir = config.output_directory.full?
+          generate_to dir
+        else
+          fail "Specify an output_directory in your configuration!"
+        end
+      end
+
+      def generate_to(dirname)
+        configure_for_creation
+        prepare_dir dirname
+        create_sections(dirname)
+        create_readme dirname
+        create_assets
+        self
+      end
+
+      def configure_for_creation
+        STDERR.puts "Setting asset_host to #{Betterdocs::Global.asset_host.inspect}."
+        Betterdocs.rails.configuration.action_controller.asset_host = Betterdocs::Global.asset_host
+        options = {
+          host:     Betterdocs::Global.api_host,
+          protocol: Betterdocs::Global.api_protocol
+        }
+        STDERR.puts "Setting default_url_options to #{options.inspect}."
+        Betterdocs.rails.application.routes.default_url_options = options
+        self
+      end
+
+      def create_sections(dirname)
+        cd dirname do
+          for section in sections.values
+            if @only
+              @only =~ section.name or next
+            end
+            STDERR.puts on_color(33, "Creating section #{section.name.inspect}.")
+            render_to "sections/#{section.name}.md", section_template, section.instance_eval('binding')
+          end
+        end
+        self
+      end
+
+      def create_readme(dirname)
+        name = 'README.md'
+        cd dirname do
+          STDERR.puts on_color(33, "Creating readme.")
+          render_to name, readme_template, binding
+        end
+        self
+      end
+
+      def create_assets
+        config.each_asset do |src, dst|
+          STDERR.puts on_color(33, "Creating asset #{dst.inspect} from #{src.inspect}.")
+          mkdir_p File.dirname(dst)
+          cp src, dst
+        end
+      end
+
+      private
+
+      def fail_while_rendering(template, exception)
+        message = blink(color(231, on_color(
+          124, " *** ERROR #{exception.class}: #{exception.message.inspect} in template ***")))
+        STDERR.puts message
+        Timeout.timeout(5, Timeout::Error) do
+          STDERR.print "Output long error message? (yes/NO) "
+          if STDIN.gets =~ /\Ay/i
+            STDERR.puts color(88, on_color(136, template)), message,
+              color(136, (%w[Backtrace:] + exception.backtrace) * "\n"),
+              message
+          end
+        end
+      rescue Timeout::Error
+        STDERR.puts "Nope…"
+      ensure
+        exit 1
+      end
+
+      def render_to(filename, template, binding)
+        File.open(filename, 'w') do |output|
+          rendered = ERB.new(template, nil, '-').result(binding)
+          output.write rendered
+        end
+        self
+      rescue => e
+        fail_while_rendering(template, e)
+      end
+
+      def default_templates_directory
+        File.join File.dirname(__FILE__), 'markdown', 'templates'
+      end
+
+      def read_template(filename)
+        STDERR.puts "Now reading #{filename.inspect}."
+        File.read(filename)
+      end
+
+      def provide_template(template_subpath)
+        if templates_directory = config.full?(:templates_directory)
+          path = File.expand_path(template_subpath, templates_directory)
+          File.file?(path) and return read_template(path)
+        end
+        path = File.expand_path(template_subpath, default_templates_directory)
+        File.file?(path) and return read_template(path)
+          message = "#{template_subpath.inspect} missing"
+        STDERR.puts " *** #{message}"
+        "[#{message}]"
+      end
+
+      def readme_template
+        provide_template 'README.md.erb'
+      end
+      memoize_method :readme_template
+
+      def section_template
+        provide_template 'section.md.erb'
+      end
+      memoize_method :section_template
+
+      def prepare_dir(dirname)
+        dirname.present? or raise ArgumentError,
+          "#{dirname.inspect} should be an explicite output dirname"
+        begin
+          stat = File.stat(dirname)
+          if stat.directory?
+            rm_rf Dir[dirname.to_s + '/**/*']
+          else
+            raise ArgumentError, "#{dirname.inspect} is not a directory"
+          end
+        rescue Errno::ENOENT
+        end
+        mkdir_p "#{dirname}/sections"
+        self
+      end
+    end
+  end
+end