markdown_ruby_documentation 0.1.0

data/lib/markdown_ruby_documentation.rb

@@ -0,0 +1,29 @@
+require "markdown_ruby_documentation/version"
+require "markdown_ruby_documentation/summary"
+require "markdown_ruby_documentation/instance_to_class_methods"
+require "markdown_ruby_documentation/print_method_source"
+require "markdown_ruby_documentation/template_parser"
+require "markdown_ruby_documentation/markdown_presenter"
+require "markdown_ruby_documentation/generate"
+require "markdown_ruby_documentation/git_hub_link"
+require "markdown_ruby_documentation/git_hub_project"
+require "markdown_ruby_documentation/reject_blank_methods"
+require "markdown_ruby_documentation/method_linker"
+require "markdown_ruby_documentation/method"
+require "markdown_ruby_documentation/method/instance_method"
+require "markdown_ruby_documentation/method/class_method"
+require "markdown_ruby_documentation/method/null_method"
+require "markdown_ruby_documentation/write_markdown_to_disk"
+require "markdown_ruby_documentation/default_erb_methods"
+require "markdown_ruby_documentation/constants_presenter"
+require "ruby-progressbar"
+require "active_support/core_ext/string"
+require "method_source"
+require "json"
+require "active_support/dependencies/autoload"
+require "active_support/number_helper"
+
+module MarkdownRubyDocumentation
+  START_TOKEN = "=mark_doc".freeze
+  END_TOKEN   = "=mark_end".freeze
+end

data/lib/markdown_ruby_documentation/constants_presenter.rb

@@ -0,0 +1,38 @@
+module MarkdownRubyDocumentation
+  class ConstantsPresenter
+
+    attr_reader :subject
+
+    def initialize(subject)
+      @subject = subject
+    end
+
+    def call(interface)
+      constants.each do |const_name, value|
+        interface[const_name] = { text: value, method_object: Method.create("#{subject.name}::#{const_name}", null_method: true) }
+      end
+      interface
+    end
+
+    private
+
+    def constants
+      subject.constants.each_with_object({}) do |v, const|
+        c        = subject.const_get(v)
+        const[v] = format(c) unless c.class == Module || c.class == Class
+      end
+    end
+
+    def format(value)
+      case value
+      when Fixnum
+        ActiveSupport::NumberHelper.number_to_delimited(value)
+      when String
+        value.inspect
+      else
+        value
+      end
+    end
+
+  end
+end

data/lib/markdown_ruby_documentation/default_erb_methods.rb

@@ -0,0 +1,11 @@
+module MarkdownRubyDocumentation
+  module DefaultErbMethods
+    def link_to_markdown(klass, title:)
+      "[#{title}](#{klass})"
+    end
+
+    def self.erb_methods_module
+      self
+    end
+  end
+end

data/lib/markdown_ruby_documentation/generate.rb

@@ -0,0 +1,107 @@
+module MarkdownRubyDocumentation
+  class Generate
+    # @param [Class] subjects ruby classes to generate documentation from.
+    # @param [Module] erb_methods must contain #link_to_markdown and contain any additional methods for comment ERB
+    # @param [Proc] output_proc given name: and text: for use in saving the the files.
+    def self.run(
+      subjects:, erb_methods: DefaultErbMethods, output_proc: -> (name:, text:) { { name => text } }
+    )
+      erb_methods_class = Class.new
+      erb_methods_class.extend TemplateParser::CommentMacros
+      erb_methods_class.extend erb_methods
+      TemplateParser::CommentMacros.include erb_methods
+      left_padding = subjects.map(&:name).group_by(&:size).max.first
+      progressbar = ProgressBar.create(title: "Compiling Markdown".ljust(left_padding), total: subjects.count+ 1)
+      pages       = subjects.map do |subject|
+        progressbar.title = subject.name.ljust(left_padding)
+        Page.new(subject:           subject,
+                 output_proc:       output_proc,
+                 erb_methods_class: erb_methods_class).call.tap { progressbar.increment }
+      end
+
+      return_value = pages.each_with_object({}) do |page, hash|
+        name_parts      = page.subject.name.split("::")
+        name            = name_parts.pop
+        namespace       = name_parts.join("::")
+        hash[namespace] ||= {}
+        hash[namespace].merge!({ name => page })
+        hash
+      end
+      progressbar.title = "Markdown Documentation Compilation Complete".ljust(left_padding)
+      progressbar.finish
+      return_value
+    end
+
+    class Page
+      attr_reader :subject, :output_proc, :erb_methods_class
+
+      def initialize(subject:,
+                     methods: [],
+                     output_proc:,
+                     erb_methods_class:)
+        initialize_methods(methods, subject)
+        @erb_methods_class = erb_methods_class
+        @subject           = subject
+        methods            = methods
+        @methods           = methods
+        @output_proc       = output_proc
+      end
+
+      def call
+        methods_pipes = run_pipeline(methods_pipeline)
+        text          = run_pipeline(string_pipeline, methods_pipes)
+        output_proc.call(name: subject.name,
+                         text: text)
+        self
+      end
+
+      private
+      def initialize_methods(methods, subject)
+        if methods.empty?
+          all_instance_and_class_methods(methods, subject)
+        else
+          methods.map! { |method| method.is_a?(Symbol) ? InstanceMethod.new("#{subject.name}##{method}", context: subject) : method }
+        end
+      end
+
+      def all_instance_and_class_methods(methods, subject)
+        instance_m = subject.instance_methods(false).concat(subject.private_instance_methods(false))
+        klass_m    = subject.methods(false).concat(subject.private_methods(false)) - Object.methods
+        methods.concat instance_m.map { |method| InstanceMethod.new("#{subject.name}##{method}", context: subject) }
+        methods.concat klass_m.map { |method| ClassMethod.new("#{subject.name}.#{method}", context: subject) }
+      end
+
+      def methods_pipeline
+        [
+          TemplateParser.new(subject, @methods),
+          RejectBlankMethod,
+          GitHubLink.new(subject: subject),
+          ConstantsPresenter.new(subject),
+          MarkdownPresenter.new(summary: summary, title_key: section_key),
+        ]
+      end
+
+      def string_pipeline
+        [
+          MethodLinker.new(section_key: section_key, root_path: "./"),
+        ]
+      end
+
+      def summary
+        @summary ||= Summary.new(subject: subject, erb_methods_class: erb_methods_class)
+      end
+
+      def run_pipeline(pipeline, last_result=nil)
+        last_result ||= pipeline.shift.call
+        pipeline.each do |pipe|
+          last_result = pipe.call(last_result)
+        end
+        last_result
+      end
+
+      def section_key
+        subject.name.underscore.gsub("/", "-")
+      end
+    end
+  end
+end

data/lib/markdown_ruby_documentation/git_hub_link.rb

@@ -0,0 +1,74 @@
+module MarkdownRubyDocumentation
+  class GitHubLink
+    attr_reader :subject, :base_url, :root
+
+    def initialize(subject:, base_url: GitHubProject.url, root: GitHubProject.root_path)
+      @subject  = subject
+      @base_url = base_url
+      @root     = root
+    end
+
+    def call(hash)
+      hash.each do |name, values|
+        hash[name][:text] = "#{values[:text]}\n\n[show on github](#{create_link(name: name, method_object: values[:method_object])})"
+      end
+    end
+
+    def create_link(name: nil, method_object: nil)
+      if name && method_object.nil?
+        method_object = Method.create("##{name}")
+      end
+      MethodUrl.new(subject: subject, base_url: base_url, root: root, method_object: method_object).to_s
+    end
+
+    class FileUrl
+      attr_reader :file_path, :base_url, :root
+
+      def initialize(file_path:, base_url: GitHubProject.url, root: GitHubProject.root_path)
+        @file_path = file_path
+        @base_url  = base_url
+        @root      = root
+      end
+
+      def to_s
+        link(file_path)
+      end
+
+      def to_pathname
+        Pathname(to_s)
+      end
+
+      def link(file, lineno=nil)
+        str = File.join(base_url, "blob", blob(file), relative_path(file))
+        unless lineno.nil?
+          str << "#L#{lineno}"
+        end
+        str.chomp
+      end
+
+      def blob(file)
+        GitHubProject.branch
+      end
+
+      def relative_path(file)
+        file.sub(root, "")
+      end
+    end
+
+    class MethodUrl
+      attr_reader :base_url, :method_object, :subject, :root
+
+      def initialize(subject:, method_object:, base_url: GitHubProject.url, root: GitHubProject.root_path)
+        @subject       = subject
+        @base_url      = base_url
+        @root          = root
+        @method_object = method_object
+      end
+
+      def to_s
+        file, lineno = subject.public_send(method_object.type, method_object.name).source_location
+        FileUrl.new(file_path: file, base_url: base_url, root: root).link(file, lineno)
+      end
+    end
+  end
+end

data/lib/markdown_ruby_documentation/git_hub_project.rb

@@ -0,0 +1,29 @@
+module MarkdownRubyDocumentation
+  class GitHubProject
+    class << self
+      def git_url
+        `git config --get remote.origin.url`.chomp
+      end
+
+      def url
+        "https://github.com/#{git_url.split(":").last.gsub(".git", "")}".chomp
+      end
+
+      def root_path
+        `git rev-parse --show-toplevel`.chomp
+      end
+
+      def set_branch(branch)
+        @branch = branch
+      end
+
+      def branch
+        @branch || current_branch
+      end
+
+      def current_branch
+        `git rev-parse --abbrev-ref HEAD`.chomp
+      end
+    end
+  end
+end

data/lib/markdown_ruby_documentation/instance_to_class_methods.rb

@@ -0,0 +1,44 @@
+module MarkdownRubyDocumentation
+  class InstanceToClassMethods
+    attr_reader :method_object
+
+    def initialize(method:)
+      @method_object = method
+    end
+
+    def eval_instance_method
+      _module = method_object.context.const_set(new_class_name, Class.new(method_object.context))
+      rescue_and_define_method(_module) do |_module|
+        create_method(method_object, _module)
+        _module.send(method_object.name)
+      end
+    end
+
+    private
+
+    def new_class_name
+      "InstanceToClassMethods#{method_object.context.name}#{('A'..'Z').to_a.sample(5).join}".delete("::")
+    end
+
+    def rescue_and_define_method(_module, &block)
+      block.call(_module)
+    rescue NameError => e
+      if (undefined_method = e.message.match(/undefined local variable or method `(.+)'/).try!(:captures).try!(:first))
+        undefined_method = Method.create("##{undefined_method}", context: method_object.context)
+        create_method(undefined_method, _module)
+        rescue_and_define_method(_module, &block)
+      else
+        raise e
+      end
+    end
+
+    def create_method(method, m=Module.new)
+      m.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def self.#{method.name}
+      #{PrintMethodSource.new(method: method).print}
+            end
+      RUBY
+      m
+    end
+  end
+end

data/lib/markdown_ruby_documentation/markdown_presenter.rb

@@ -0,0 +1,36 @@
+module MarkdownRubyDocumentation
+  class MarkdownPresenter
+
+    attr_reader :items, :title_key, :summary
+
+    def initialize(items: nil, summary:, title_key:, skip_blanks: true)
+      @items       = items
+      @summary     = summary
+      @title_key   = title_key
+      @skip_blanks = skip_blanks
+    end
+
+    def call(items=nil)
+      @items ||= items
+      <<-MD
+# #{summary.title}
+#{summary.summary}
+
+#{present_items}
+      MD
+    end
+
+    private
+
+    def present_items
+      items.map do |name, hash|
+        begin
+        %[## #{name.to_s.titleize}\n#{hash[:text]}] unless hash[:text].blank?
+        rescue =>e
+        puts e
+          end
+      end.join("\n\n")
+    end
+
+  end
+end

data/lib/markdown_ruby_documentation/method.rb

@@ -0,0 +1,101 @@
+module MarkdownRubyDocumentation
+  class Method
+    attr_reader :method_reference
+    protected :method_reference
+
+    def initialize(method_reference, context: Kernel)
+      @method_reference = method_reference.to_s
+      @context          = context
+    end
+
+    # @param [String] method_reference
+    # @example
+    #   ".class_method_name" class method in the current scope.
+    #   "Constant.class_method_name" class method on a specific constant.
+    #   "SomeClass#instance_method_name" an instance method on a specific constant.
+    #   "#instance_method_name" an instance method in the current scope.
+    def self.create(method_reference, null_method: false, context: Kernel)
+      case method_reference
+      when InstanceMethod
+        InstanceMethod.new(method_reference, context: context)
+      when ClassMethod
+        ClassMethod.new(method_reference, context: context)
+      else
+        if null_method
+          NullMethod.new(method_reference, context: context)
+        else
+          raise ArgumentError, "method_reference is formatted incorrectly: '#{method_reference}'"
+        end
+      end
+    end
+
+    def ==(other_method)
+      self.class == other_method.class && other_method.method_reference == self.method_reference
+    end
+
+    alias :eql? :==
+
+    def hash
+      @method_reference.hash
+    end
+
+    def self.===(value)
+      if value.is_a?(String)
+        value.include?(type_symbol)
+      else
+        super
+      end
+    end
+
+    # @return [String]
+    def type_symbol
+      self.class.type_symbol
+    end
+
+    # @return [Class]
+    def context
+      if method_reference.start_with?(type_symbol)
+        @context
+      else
+        constant = method_reference.split(type_symbol).first
+        begin
+          constant.constantize
+        rescue NameError => e
+          @context.const_get(constant)
+        end
+      end
+    end
+
+    def context_name
+      if method_reference.start_with?(type_symbol)
+        @context.name
+      else
+        method_reference.split(type_symbol).first
+      end
+    end
+
+    # @return [Symbol]
+    def name
+      method_reference.split(type_symbol).last.try!(:to_sym)
+    end
+
+    # @return [String]
+    def to_s
+      method_reference
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{to_s}>"
+    end
+
+    # @return [Proc]
+    def to_proc
+      context.public_send(type, name)
+    end
+
+    def type
+      raise NotImplementedError
+    end
+  end
+end