Routes markdown (#429)

.rubocop_todo.yml

 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2016-12-16 13:08:29 +0100 using RuboCop version 0.46.0.
+# on 2016-12-17 10:16:05 +0100 using RuboCop version 0.46.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -101,14 +101,14 @@ Lint/UselessAccessModifier:
   Exclude:
     - 'lib/annotate/annotate_routes.rb'
 
-# Offense count: 16
+# Offense count: 17
 Metrics/AbcSize:
   Max: 144
 
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/BlockLength:
-  Max: 135
+  Max: 134
 
 # Offense count: 2
 Metrics/BlockNesting:
@@ -118,17 +118,22 @@ Metrics/BlockNesting:
 Metrics/CyclomaticComplexity:
   Max: 36
 
-# Offense count: 339
+# Offense count: 350
 # Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
 # URISchemes: http, https
 Metrics/LineLength:
   Max: 543
 
-# Offense count: 23
+# Offense count: 24
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
   Max: 70
 
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ModuleLength:
+  Max: 116
+
 # Offense count: 7
 Metrics/PerceivedComplexity:
   Max: 41
@@ -254,12 +259,13 @@ Style/ExtraSpacing:
     - 'spec/integration/rails_4.2.0/Gemfile'
     - 'spec/integration/rails_4.2.0/config.ru'
 
-# Offense count: 8
+# Offense count: 9
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 # SupportedStyles: format, sprintf, percent
 Style/FormatString:
   Exclude:
     - 'lib/annotate/annotate_models.rb'
+    - 'lib/annotate/annotate_routes.rb'
 
 # Offense count: 181
 # Cop supports --auto-correct.
@@ -284,14 +290,6 @@ Style/GuardClause:
 Style/HashSyntax:
   Enabled: false
 
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles, IndentationWidth.
-# SupportedStyles: special_inside_parentheses, consistent, align_brackets
-Style/IndentArray:
-  Exclude:
-    - 'lib/annotate/annotate_routes.rb'
-
 # Offense count: 6
 # Cop supports --auto-correct.
 # Configuration parameters: SupportedStyles, IndentationWidth.
@@ -437,7 +435,7 @@ Style/Semicolon:
     - 'bin/annotate'
     - 'spec/integration/rails_2.3_with_bundler/config/initializers/unified_initializer.rb'
 
-# Offense count: 4
+# Offense count: 3
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 # SupportedStyles: space, no_space
@@ -519,7 +517,7 @@ Style/SpaceInsideStringInterpolation:
   Exclude:
     - 'lib/annotate/annotate_models.rb'
 
-# Offense count: 222
+# Offense count: 223
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles, ConsistentQuotesInMultiline.
 # SupportedStyles: single_quotes, double_quotes
@@ -570,18 +568,18 @@ Style/TrailingCommaInLiteral:
     - 'spec/integration/rails_4.1.1/lib/tasks/auto_annotate_models.rake'
     - 'spec/integration/rails_4.2.0/lib/tasks/auto_annotate_models.rake'
 
-# Offense count: 1
+# Offense count: 2
 # Cop supports --auto-correct.
 Style/TrailingWhitespace:
   Exclude:
+    - 'spec/annotate/annotate_routes_spec.rb'
     - 'spec/integration/rails_2.3_with_bundler/db/schema.rb'
 
-# Offense count: 3
+# Offense count: 2
 # Cop supports --auto-correct.
 Style/UnneededInterpolation:
   Exclude:
     - 'bin/annotate'
-    - 'lib/annotate/annotate_routes.rb'
 
 # Offense count: 8
 # Cop supports --auto-correct.

bin/annotate

@@ -90,12 +90,11 @@ OptionParser.new do |opts|
     ENV['routes'] = 'true'
   end
 
-  opts.on('-aa', '--active-admin', 'Annotate active_admin models') do |p|
-    ENV['active_admin'] = p
+  opts.on('-aa', '--active-admin', 'Annotate active_admin models') do
+    ENV['active_admin'] = 'true'
   end
 
-  opts.on('-v', '--version',
-          'Show the current version of this gem') do
+  opts.on('-v', '--version', 'Show the current version of this gem') do
     puts "annotate v#{Annotate.version}"; exit
   end
 

lib/annotate/annotate_routes.rb

@@ -18,33 +18,60 @@
 # Released under the same license as Ruby. No Support. No Warranty.
 #
 module AnnotateRoutes
-  PREFIX = '# == Route Map'
+  PREFIX = '== Route Map'.freeze
+  PREFIX_MD = '## Route Map'.freeze
+  HEADER_ROW = ['Prefix', 'Verb', 'URI Pattern', 'Controller#Action']
 
-  def self.do_annotations(options={})
-    return unless routes_exists?
+  class << self
+    def content(line, maxs, options = {})
+      return line.rstrip unless options[:format_markdown]
 
-    routes_map = AnnotateRoutes.app_routes_map(options)
+      line.each_with_index.map do |elem, index|
+        min_length = maxs.map { |arr| arr[index] }.max || 0
 
-    header = [
-        "#{PREFIX}" + (options[:timestamp] ? " (Updated #{Time.now.strftime('%Y-%m-%d %H:%M')})" : ''), '#'
-    ] + routes_map.map { |line| "# #{line}".rstrip }
+        sprintf("%-#{min_length}.#{min_length}s", elem.tr('|', '-'))
+      end.join(' | ')
+    end
+
+    def header(options = {})
+      routes_map = app_routes_map(options)
+
+      out = ["# #{options[:format_markdown] ? PREFIX_MD : PREFIX}" + (options[:timestamp] ? " (Updated #{Time.now.strftime('%Y-%m-%d %H:%M')})" : '')]
+      out += ['#']
+      return out if routes_map.size.zero?
 
-    existing_text = File.read(routes_file)
+      maxs = [HEADER_ROW.map(&:size)] + routes_map[1..-1].map { |line| line.split.map(&:size) }
+      max = maxs.map(&:max).max
 
-    if write_contents(existing_text, header, options)
-      puts "#{routes_file} annotated."
+      if options[:format_markdown]
+        out += ["# #{content(HEADER_ROW, maxs, options)}"]
+        out += ["# #{content(['-' * max, '-' * max, '-' * max, '-' * max], maxs, options)}"]
+      else
+        out += ["# #{content(routes_map[0], maxs, options)}"]
+      end
+
+      out + routes_map[1..-1].map { |line| "# #{content(options[:format_markdown] ? line.split(' ') : line, maxs, options)}" }
     end
-  end
 
-  def self.remove_annotations(options={})
-    return unless routes_exists?
-    existing_text = File.read(routes_file)
-    content, where_header_found = strip_annotations(existing_text)
+    def do_annotations(options = {})
+      return unless routes_exists?
+      existing_text = File.read(routes_file)
+
+      if write_contents(existing_text, header(options), options)
+        puts "#{routes_file} annotated."
+      end
+    end
+
+    def remove_annotations(options={})
+      return unless routes_exists?
+      existing_text = File.read(routes_file)
+      content, where_header_found = strip_annotations(existing_text)
 
-    content = strip_on_removal(content, where_header_found)
+      content = strip_on_removal(content, where_header_found)
 
-    if write_contents(existing_text, content, options)
-      puts "Removed annotations from #{routes_file}."
+      if write_contents(existing_text, content, options)
+        puts "Removed annotations from #{routes_file}."
+      end
     end
   end
 

potato.md

+Colons can be used to align columns.
+
+| Tables        | Are           | Cool  |
+| ------------- |:-------------:| -----:|
+| col 3 is      | right-aligned | $1600 |
+| col 2 is      | centered      |   $12 |
+| zebra stripes | are neat      |    $1 |
+
+There must be at least 3 dashes separating each header cell.
+The outer pipes (|) are optional, and you don't need to make the
+raw Markdown line up prettily. You can also use inline Markdown.
+
+Markdown | Less | Pretty
+--- | --- | ---
+*Still* | `renders` | **nicely**
+1 | 2 | 3
+
+
+ ## Route Map
+
+  Prefix    | Verb       | URI Pattern     | Controller#Action    
+  --------- | ---------- | --------------- | --------------------
+  myaction1 | GET        | /url1(.:format) | mycontroller1#action
+  myaction2 | POST       | /url2(.:format) | mycontroller2#action
+  myaction3 | DELETE-GET | /url3(.:format) | mycontroller3#action \n")
+
+
+
+ Table name: `users`
+
+ ### Columns
+
+ Name                    | Type               | Attributes
+ ----------------------- | ------------------ | ---------------------------
+ **`id`**                | `integer`          | `not null, primary key`
+ **`foreign_thing_id`**  | `integer`          | `not null`
+
+ ### Foreign Keys
+
+ * `fk_rails_...` (_ON DELETE => on_delete_value ON UPDATE => on_update_value_):
+     * **`foreign_thing_id => foreign_things.id`**

spec/annotate/annotate_routes_spec.rb

@@ -17,6 +17,47 @@ describe AnnotateRoutes do
     AnnotateRoutes.do_annotations
   end
 
+  describe 'Annotate#example' do
+    before(:each) do
+      expect(File).to receive(:exists?).with(ROUTE_FILE).and_return(true)
+
+      expect(File).to receive(:read).with(ROUTE_FILE).and_return("")
+      expect(AnnotateRoutes).to receive(:`).with('rake routes').and_return('                                      Prefix Verb       URI Pattern                                               Controller#Action
+                                   myaction1 GET        /url1(.:format)                                           mycontroller1#action
+                                   myaction2 POST       /url2(.:format)                                           mycontroller2#action
+                                   myaction3 DELETE|GET /url3(.:format)                                           mycontroller3#action')
+
+      expect(AnnotateRoutes).to receive(:puts).with(ANNOTATION_ADDED)
+    end
+
+    it 'annotate normal' do
+      expect(File).to receive(:open).with(ROUTE_FILE, 'wb').and_yield(mock_file)
+      expect(@mock_file).to receive(:puts).with("
+# == Route Map
+#
+#                                       Prefix Verb       URI Pattern                                               Controller#Action
+#                                    myaction1 GET        /url1(.:format)                                           mycontroller1#action
+#                                    myaction2 POST       /url2(.:format)                                           mycontroller2#action
+#                                    myaction3 DELETE|GET /url3(.:format)                                           mycontroller3#action\n")
+
+      AnnotateRoutes.do_annotations
+    end
+
+    it 'annotate markdown' do
+      expect(File).to receive(:open).with(ROUTE_FILE, 'wb').and_yield(mock_file)
+      expect(@mock_file).to receive(:puts).with("
+# ## Route Map
+#
+# Prefix    | Verb       | URI Pattern     | Controller#Action   
+# --------- | ---------- | --------------- | --------------------
+# myaction1 | GET        | /url1(.:format) | mycontroller1#action
+# myaction2 | POST       | /url2(.:format) | mycontroller2#action
+# myaction3 | DELETE-GET | /url3(.:format) | mycontroller3#action\n")
+
+      AnnotateRoutes.do_annotations(format_markdown: true)
+    end
+  end
+
   describe 'When adding' do
     before(:each) do
       expect(File).to receive(:exists?).with(ROUTE_FILE).and_return(true)