guides: adds support in the indexer for custom header IDs, and some refactors

railties/guides/rails_guides/generator.rb

@@ -48,6 +48,7 @@
 require 'fileutils'
 
 require 'active_support/core_ext/string/output_safety'
+require 'active_support/core_ext/object/blank'
 require 'action_controller'
 require 'action_view'
 
@@ -57,14 +58,14 @@
 
 module RailsGuides
   class Generator
-    attr_reader :guides_dir, :source_dir, :output_dir, :edge
+    attr_reader :guides_dir, :source_dir, :output_dir, :edge, :warnings, :all
 
     GUIDES_RE = /\.(?:textile|html\.erb)$/
 
     def initialize(output=nil)
       initialize_dirs(output)
       create_output_dir_if_needed
-      set_edge
+      set_flags_from_environment
     end
 
     def generate
@@ -83,8 +84,10 @@ def create_output_dir_if_needed
       FileUtils.mkdir_p(output_dir)
     end
 
-    def set_edge
-      @edge = ENV['EDGE'] == '1'
+    def set_flags_from_environment
+      @edge     = ENV['EDGE']     == '1'
+      @warnings = ENV['WARNINGS'] == '1'
+      @all      = ENV['ALL']      == '1'
     end
 
     def generate_guides
@@ -117,7 +120,7 @@ def output_file_for(guide)
     def generate?(source_file, output_file)
       fin  = File.join(source_dir, source_file)
       fout = File.join(output_dir, output_file)
-      ENV['ALL'] == '1' || !File.exists?(fout) || File.mtime(fout) < File.mtime(fin)
+      all || !File.exists?(fout) || File.mtime(fout) < File.mtime(fin)
     end
 
     def generate_guide(guide, output_file)
@@ -136,7 +139,7 @@ def generate_guide(guide, output_file)
 
           result = view.render(:layout => 'layout', :text => textile(body))
 
-          warn_about_broken_links(result) if ENV['WARNINGS'] == '1'
+          warn_about_broken_links(result) if @warnings
         end
 
         f.write result
@@ -164,16 +167,16 @@ def set_index(body, view)
         <ol class="chapters">
       INDEX
 
-      i = Indexer.new(body)
+      i = Indexer.new(body, warnings)
       i.index
 
       # Set index for 2 levels
       i.level_hash.each do |key, value|
-        link = view.content_tag(:a, :href => key[:id]) { textile(key[:title]).html_safe }
+        link = view.content_tag(:a, :href => key[:id]) { textile(key[:title], true).html_safe }
 
         children = value.keys.map do |k|
-          l = view.content_tag(:a, :href => k[:id]) { textile(k[:title]).html_safe }
-          view.content_tag(:li, l.html_safe)
+          view.content_tag(:li,
+            view.content_tag(:a, :href => k[:id]) { textile(k[:title], true).html_safe })
         end
 
         children_ul = children.empty? ? "" : view.content_tag(:ul, children.join(" ").html_safe)
@@ -189,11 +192,12 @@ def set_index(body, view)
       i.result
     end
 
-    def textile(body)
+    def textile(body, lite_mode=false)
       # If the issue with notextile is fixed just remove the wrapper.
       with_workaround_for_notextile(body) do |body|
         t = RedCloth.new(body)
         t.hard_breaks = false
+        t.lite_mode = lite_mode
         t.to_html(:notestuff, :plusplus, :code, :tip)
       end
     end

railties/guides/rails_guides/indexer.rb

+require 'active_support/core_ext/object/blank'
+require 'active_support/ordered_hash'
+
 module RailsGuides
   class Indexer
-    attr_reader :body, :result, :level_hash
+    attr_reader :body, :result, :warnings, :level_hash
 
-    def initialize(body)
-      @body = body
-      @result = @body.dup
+    def initialize(body, warnings)
+      @body     = body
+      @result   = @body.dup
+      @warnings = warnings
     end
 
     def index
@@ -13,29 +17,30 @@ def index
 
     private
 
-    def process(string, current_level= 3, counters = [1])
+    def process(string, current_level=3, counters=[1])
       s = StringScanner.new(string)
 
       level_hash = ActiveSupport::OrderedHash.new
 
       while !s.eos?
-        s.match?(/h[0-9]\..*$/)
+        re = %r{^h(\d)(?:\((#.*?)\))?\s*\.\s*(.*)$}
+        s.match?(re)
         if matched = s.matched
-          matched =~ /h([0-9])\.(.*)$/
-          level, title = $1.to_i, $2
+          matched =~ re
+          level, idx, title = $1.to_i, $2, $3.strip
 
           if level < current_level
             # This is needed. Go figure.
             return level_hash
           elsif level == current_level
             index = counters.join(".")
-            bookmark = '#' + title.strip.downcase.gsub(/\s+|_/, '-').delete('^a-z0-9-')
+            idx ||= '#' + title_to_idx(title)
 
-            raise "Parsing Fail" unless @result.sub!(matched, "h#{level}(#{bookmark}). #{index}#{title}")
+            raise "Parsing Fail" unless @result.sub!(matched, "h#{level}(#{idx}). #{index} #{title}")
 
             key = {
               :title => title,
-              :id => bookmark
+              :id => idx
             }
             # Recurse
             counters << 1
@@ -51,5 +56,13 @@ def process(string, current_level= 3, counters = [1])
       end
       level_hash
     end
+
+    def title_to_idx(title)
+      idx = title.strip.downcase.gsub(/\s+|_/, '-').delete('^a-z0-9-').sub(/^[^a-z]*/, '')
+      if warnings && idx.blank?
+        puts "BLANK ID: please put an explicit ID for section #{title}, as in h5(#my-id)"
+      end
+      idx
+    end
   end
 end

railties/guides/source/action_view_overview.textile

@@ -1304,7 +1304,7 @@ h4. PrototypeHelper::JavaScriptGenerator::GeneratorMethods
 
 JavaScriptGenerator generates blocks of JavaScript code that allow you to change the content and presentation of multiple DOM elements. Use this in your Ajax response bodies, either in a +script+ tag or as plain JavaScript sent with a Content-type of "text/javascript".
 
-h5. <<
+h5(#push). <<
 
 Writes raw JavaScript to the page.
 
@@ -1312,7 +1312,7 @@ Writes raw JavaScript to the page.
 page << "alert('JavaScript with Prototype.');"
 </ruby>
 
-h5. []
+h5(#at). []
 
 Returns a element reference by finding it through it's id in the DOM.