markdown_ruby_documentation 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 98da1a6202c25d0e20c630339f0ec5c9c6bb1898
-  data.tar.gz: 6af3bf690dd9f17d014ea6c5cc28eca39e975172
+  metadata.gz: 0195aa8a642b4e01747ef74e449c4a0e0195fcc5
+  data.tar.gz: c752bf835f1c6fbf3bbf5ed968cc35a3810bb930
 SHA512:
-  metadata.gz: 333233006d8b7304ed481d52b0b5d38b2b7605d644fae481d584be890ac59af4f9b3c43faaa8c29cc2f1e6dc3fa954fcb18d7481060640e86be4abb014188eb0
-  data.tar.gz: a06f239ab1f24aabf81c63e0adf2f34f35d01a4df7558d2a5f1eed1119d5393991c64a83ea6b721e4097be79846ada30dc425e349a49b514a641650e204858e1
+  metadata.gz: a736068cff89585b1efa8dbce9dc0854effea63f90a38819dbe75c406594240824162f0e297c6095054e65824caeae4abf47f19d76fecafc7b445caa9566ca92
+  data.tar.gz: c2ce815983eb44535d554e0599a61588a9f1d7adff1892ad52330f3256fb6eb7a28575af2a198aa625de755f34e3483df4f920dc1aa1ad4e6f32c81673d2dd5b

data/README.md

@@ -40,7 +40,7 @@ html_generator  = MarkdownRubyDocumentation::HtmlGenerator.new(
 
 MarkdownRubyDocumentation::Generate.run(
   subjects:     [RubyClassToBeInspected], 
-  output_proc:  html_generator
+  output_object:  html_generator
 ).call
 ```
 
@@ -94,7 +94,8 @@ Converts case statements and if statements to bulleted markdown
    *example ruby_to_markdown "def method_name\n'hello'\nend", readable_ruby_numbers: false**
  **option 2 - Assumes methods source of current method**
    * param [Hash] disable_processors (optional) See processors list.
-   *example ruby_to_markdown readable_ruby_numbers: false*
+   `example ruby_to_markdown(readable_ruby_numbers: false)`
+   `example ruby_to_markdown(ruby_operators_to_english: { proc: ->(replacement, match) { "do some alteration" }})`
    
 **processors**
 * readable_ruby_numbers
@@ -103,8 +104,9 @@ Converts case statements and if statements to bulleted markdown
 * ternary_to_if_else
 * ruby_if_statement_to_md
 * ruby_case_statement_to_md
-* ruby_operators_to_english
-* methods_as_local_links
+* ruby_operators_to_english, options: proc(replacement, match)
+* methods_as_local_links, options: method_to_class: { method_name => OwningConstant }
+* question_mark_method_format
 * remove_end_keyword
 * constants_with_name_and_value
 * remove_memoized_vars

data/lib/markdown_ruby_documentation/default_erb_methods.rb

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

data/lib/markdown_ruby_documentation/generate.rb

@@ -2,24 +2,31 @@ 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.
+    # @param [Proc] output_object given name: and text: for use in saving the the files.
+    # @param [String] load_path
     def self.run(
-      subjects:, erb_methods: DefaultErbMethods, output_proc: -> (name:, text:) { { name => text } }
+      subjects:,
+        erb_methods: DefaultErbMethods,
+        output_object:,
+        load_path:
     )
-      erb_methods_class = Class.new
+      self.output_object = output_object
+      self.load_path     = load_path
+      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  = 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 }
+                 output_object:     output_object,
+                 erb_methods_class: erb_methods_class,
+                 load_path:         load_path).call.tap { progressbar.increment }
       end
 
-      return_value = pages.each_with_object({}) do |page, hash|
+      return_value      = pages.each_with_object({}) do |page, hash|
         name_parts      = page.subject.name.split("::")
         name            = name_parts.pop
         namespace       = name_parts.join("::")
@@ -32,26 +39,32 @@ module MarkdownRubyDocumentation
       return_value
     end
 
+    class << self
+      attr_accessor :load_path, :output_object
+    end
+
     class Page
-      attr_reader :subject, :output_proc, :erb_methods_class
+      attr_reader :subject, :output_object, :erb_methods_class, :load_path
 
       def initialize(subject:,
                      methods: [],
-                     output_proc:,
+                     load_path:,
+                     output_object:,
                      erb_methods_class:)
         initialize_methods(methods, subject)
         @erb_methods_class = erb_methods_class
         @subject           = subject
         methods            = methods
         @methods           = methods
-        @output_proc       = output_proc
+        @load_path         = load_path
+        @output_object     = output_object
       end
 
       def call
         methods_pipes = run_pipeline(methods_pipeline)
         text          = run_pipeline(string_pipeline, methods_pipes)
-        output_proc.call(name: subject.name,
-                         text: text)
+        output_object.call(name: subject.name,
+                           text: text)
         self
       end
 

data/lib/markdown_ruby_documentation/markdown_presenter.rb

@@ -4,33 +4,59 @@ module MarkdownRubyDocumentation
     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
+      @items         = items
+      @summary       = summary
+      @title_key     = title_key
+      @skip_blanks   = skip_blanks
+      @present_items = []
     end
 
     def call(items=nil)
       @items ||= items
-      <<-MD
-# #{summary.title}
-#{summary.summary}
-
-#{present_items}
-      MD
+      return "" if nothing_to_display?
+      md = ["# #{summary.title}", "#{summary.summary}\n".gsub(/\n\n\n/, "\n\n"), instances_methods, class_methods, "#{null_methods}\n".gsub(/\n\n\n/, "\n\n")].join("\n").gsub(/[\n]+\Z/, "\n\n")
+      other_types!
+      md
     end
 
     private
 
-    def present_items
-      items.map do |name, hash|
-        begin
+    def item_types
+      @item_types ||= items.group_by { |_, hash| hash[:method_object].class.name }
+    end
+
+    def instances_methods
+      @instance_methods ||= item_types.delete("MarkdownRubyDocumentation::InstanceMethod")  || {}
+      @instance_methods.map do |name, hash|
+        %[## #{name.to_s.titleize}\n#{hash[:text]}] unless hash[:text].blank?
+      end.join("\n\n")
+    end
+
+    def class_methods
+      @class_methods ||= item_types.delete("MarkdownRubyDocumentation::ClassMethod")  || {}
+      @class_methods.map do |name, hash|
         %[## #{name.to_s.titleize}\n#{hash[:text]}] unless hash[:text].blank?
-        rescue =>e
-        puts e
-          end
       end.join("\n\n")
     end
 
+    def null_methods
+      @null_methods ||= item_types.delete("MarkdownRubyDocumentation::NullMethod") || {}
+      md = @null_methods.map do |name, hash|
+        %[### #{name.to_s.titleize}\n#{hash[:text]}] unless hash[:text].blank?
+      end.join("\n\n")
+      if md.blank?
+        ""
+      else
+        "## Reference Values\n" << md
+      end
+    end
+
+    def other_types!
+      raise "Unhandled methods types: #{item_types}" unless item_types.empty?
+    end
+
+    def nothing_to_display?
+      [instances_methods, class_methods, null_methods].all?(&:empty?)
+    end
   end
 end

data/lib/markdown_ruby_documentation/summary.rb

@@ -9,12 +9,12 @@ class Summary
   def title
     ancestors = subject.ancestors.select do |klass|
       klass.is_a?(Class) && ![BasicObject, Object, subject].include?(klass)
-    end
+    end.sort_by { |klass| klass.name }
     [format_class(subject), *ancestors.map { |a| create_link(a) }].join(" < ")
   end
 
   def summary
-    descendants = ObjectSpace.each_object(Class).select { |klass| klass < subject && !klass.name.include?("InstanceToClassMethods") }
+    descendants = ObjectSpace.each_object(Class).select { |klass| klass < subject && !klass.name.include?("InstanceToClassMethods") }.sort_by { |klass| klass.name }
 
     descendants_links = descendants.map { |d| create_link(d) }.join(", ")
     "Descendants: #{descendants_links}" if descendants.count >= 1

data/lib/markdown_ruby_documentation/template_parser.rb

@@ -44,7 +44,7 @@ module MarkdownRubyDocumentation
       using
     )
 
-    attr_reader :ruby_class, :methods, :erb_methods_class, :current_method
+    attr_reader :ruby_class, :methods, :erb_methods_class, :current_method, :output_object, :load_path
 
     def parser
       @parser ||= methods.each_with_object({}) do |method, hash|
@@ -64,7 +64,7 @@ module MarkdownRubyDocumentation
 
     module CommentMacros
       include Parsing
-
+      attr_accessor :output_object
       # @param [String] str
       # @example
       # @return [String] of any comments proceeding a method def
@@ -184,27 +184,12 @@ module MarkdownRubyDocumentation
         gsub_replacement(source_code, conversions, proc: proc)
       end
 
-      def readable_ruby_numbers(source_code, *, &block)
+      def readable_ruby_numbers(source_code, proc: -> (value) { ActiveSupport::NumberHelper.number_to_delimited(value) })
         source_code.gsub(/([0-9][0-9_]+[0-9]+)/) do |match|
-          value = eval(match)
-          if block_given?
-            block.call(value)
-          else
-            ActiveSupport::NumberHelper.number_to_delimited(value)
-          end
+          proc.call(eval(match))
         end
       end
 
-      def include_code(include, text, &do_action)
-        if include.nil? || (include.present? && include.include?(remove_quotes(text)))
-          do_action.call(text)
-        else
-          text
-        end
-      end
-
-      private :include_code
-
       def convert_early_return_to_if_else(source_code, *)
         source_code = source_code.gsub(/(.+) if (.+)/, "if \\2\n\\1\nend")
         source_code.gsub(/(.+) unless (.+)/, "unless \\2\n\\1\nend")
@@ -235,24 +220,110 @@ module MarkdownRubyDocumentation
         [link_ref.split("/").last.split("#").last.to_s.humanize, link_ref]
       end
 
-      def link_to_markdown(klass, title:)
-        return super if defined? super
-        raise "Client needs to define MarkdownRubyDocumentation::TemplateParser::CommentMacros#link_to_markdown"
+      UnimplementedMethod = Class.new(StandardError)
+      # @param [Class, String, Pathname] klass_or_path
+      #   1. String or Class representing a method reference
+      #   2. Pathname representing the full path of the file location a method is defined
+      # @param [String] title is the link display value
+      # @return [String, Symbol] Creates link to a given generated markdown file or returns :non_project_location message.
+      #   1. "[title](path/to/markdown/file.md#method-name)"
+      #   2. :non_project_location
+      def link_to_markdown(klass_or_path, title:, _ruby_class: ruby_class)
+        if klass_or_path.is_a?(String) || klass_or_path.is_a?(Class) || klass_or_path.is_a?(Module)
+          link_to_markdown_method_reference(method_reference: klass_or_path, title: title, ruby_class: _ruby_class)
+        elsif klass_or_path.is_a?(Pathname)
+          link_to_markdown_full_path(path: klass_or_path, title: title, ruby_class: _ruby_class)
+        else
+          raise ArgumentError, "invalid first arg given: #{klass_or_path} for #{__method__}"
+        end
+      end
+
+      def link_to_markdown_method_reference(method_reference:, title:, ruby_class:)
+        method = MarkdownRubyDocumentation::Method.create(method_reference, null_method: true, context: ruby_class)
+        parts  = method.context_name.to_s.split("::").reject(&:blank?)
+        path   = parts.map { |p| p.underscore }.join("/")
+        path   = "#{path}.md#{method.type_symbol}#{method.name}"
+        format_link title, MarkdownRubyDocumentation::GitHubLink::FileUrl.new(file_path: File.join(MarkdownRubyDocumentation::Generate.output_object.relative_dir, path)).to_s
+      end
+
+      def link_to_markdown_full_path(path:, title:, ruby_class:)
+        if path.to_s.include?(MarkdownRubyDocumentation::Generate.load_path)
+          relative_path    = path.to_s.gsub(MarkdownRubyDocumentation::Generate.load_path, "")
+          const_nest, meth = relative_path.split("#")
+          const            = const_nest.split("/").map(&:camelize).join("::")
+          link_to_markdown_method_reference(method_reference: "#{const.gsub(".rb", "")}##{meth}", title: title, ruby_class: ruby_class)
+        else
+          :non_project_location
+        end
+      end
+
+      class MethodLink
+        RUBY_METHOD_REGEX = /(\b(?<!['"])[a-z_][a-z_0-9?!]*(?!['"]))/.freeze
+
+        def initialize(match:,
+                       call_on_title: :titleize,
+                       method_to_class: {},
+                       link_to_markdown:,
+                       ruby_class:)
+          @match            = match
+          @ruby_class       = ruby_class
+          @call_on_title    = call_on_title
+          @method_to_class  = method_to_class
+          @link_to_markdown = link_to_markdown
+        end
+
+        def link
+          if constant_override
+            constant_override_method_path
+          else
+            link = link_to_markdown.call(method_path, title: title)
+            if link == :non_project_location
+              match
+            else
+              link
+            end
+          end
+        rescue UnimplementedMethod => e
+          "[#{title}](##{match.downcase.dasherize.delete(" ").delete('?')})"
+        end
+
+        private
+
+        attr_reader :match, :ruby_class, :call_on_title, :method_to_class, :link_to_markdown
+
+        def title
+          @title ||= if call_on_title
+                       @call_on_title = [*call_on_title].compact
+                       match.public_send(call_on_title.first, *call_on_title[1..-1])
+                     else
+                       match
+                     end
+        end
+
+        def constant_override
+          @constant_override ||= method_to_class[match.to_sym]
+        end
+
+        def method_path
+          Pathname(Method.create("##{match}", context: ruby_class).to_proc.source_location.first+"##{match}")
+        end
+
+        def constant_override_method_path
+          method_object = Method.create("##{match}", context: constant_override)
+          link_to_markdown.call("#{method_object.context.name}##{method_object.name}", title: title)
+        end
       end
 
       def methods_as_local_links(ruby_source,
                                  call_on_title: :titleize,
-                                 proc:          -> (match, anchor) { "[#{match}](#{anchor})" })
-        ruby_source.gsub(/(\b(?<!['"])[a-z_][a-z_0-9?!]*(?!['"]))/) do |match|
+                                 method_to_class: {})
+        ruby_source.gsub(MethodLink::RUBY_METHOD_REGEX) do |match|
           if is_a_method_on_ruby_class?(match)
-
-            title = if call_on_title
-                      call_on_title = [*call_on_title].compact
-                      match.public_send(call_on_title.first, *call_on_title[1..-1])
-                    else
-                      match
-                    end
-            proc.call(title, "##{match.downcase.dasherize.delete(" ").delete('?')}")
+            MethodLink.new(match:            match,
+                           ruby_class:       ruby_class,
+                           call_on_title:    call_on_title,
+                           method_to_class:  method_to_class,
+                           link_to_markdown: method(:link_to_markdown)).link
           else
             match
           end
@@ -278,8 +349,8 @@ module MarkdownRubyDocumentation
 
       def ruby_if_statement_to_md(ruby_source, proc: false)
         conversions = {
-          /else if(.*)/ => "* __ElseIf__\\1\n__Then__",
-          /elsif(.*)/   => "* __ElseIf__\\1\n__Then__",
+          /else if(.*)/ => "* __Else If__\\1\n__Then__",
+          /elsif(.*)/   => "* __Else If__\\1\n__Then__",
           /if(.*)/      => "* __If__\\1\n__Then__",
           /unless(.*)/  => "* __Unless__\\1\n__Then__",
           "else"        => "* __Else__"

data/lib/markdown_ruby_documentation/template_parser/parsing.rb

@@ -13,6 +13,14 @@ module MarkdownRubyDocumentation
           method
         end
 
+        ruby_class.send(:define_singleton_method, :output_object) do
+          output_object
+        end
+
+        ruby_class.send(:define_singleton_method, :load_path) do
+          load_path
+        end
+
         ruby_class.extend(CommentMacros)
 
         erb          = ERB.new(str, nil, "-")

data/lib/markdown_ruby_documentation/version.rb

@@ -1,3 +1,3 @@
 module MarkdownRubyDocumentation
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/markdown_ruby_documentation/write_markdown_to_disk.rb

@@ -1,11 +1,12 @@
 module MarkdownRubyDocumentation
   class WriteMarkdownToDisk
 
-    attr_reader :dir, :skip_if_blank
+    attr_reader :dir, :skip_if_blank, :relative_dir
 
-    def initialize(dir:, skip_if_blank: false)
+    def initialize(dir:, skip_if_blank: false, relative_dir:)
       @dir           = dir
       @skip_if_blank = skip_if_blank
+      @relative_dir = relative_dir
     end
 
     def call(name:, text:)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_ruby_documentation
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dustin Zeisler
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-28 00:00:00.000000000 Z
+date: 2016-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source