Skip to content
Browse files

backslash insertion for RDoc main page ignores code blocks, also adds…

… comments to explain what's this hack about
  • Loading branch information...
1 parent edc0b2b commit e51b8fb38e24e17c278497471b926adb93088f03 @fxn fxn committed Jun 12, 2011
Showing with 19 additions and 1 deletion.
  1. +19 −1 Rakefile
View
20 Rakefile
@@ -51,9 +51,27 @@ desc "Generate documentation for the Rails framework"
RDoc::Task.new do |rdoc|
RDOC_MAIN = 'RDOC_MAIN.rdoc'
+ # This is a hack.
+ #
+ # Backslashes are needed to prevent RDoc from autolinking "Rails" to the
+ # documentation of the Rails module. On the other hand, as of this
+ # writing README.rdoc is displayed in the front page of the project in
+ # GitHub, where backslashes are shown and look weird.
+ #
+ # The temporary solution is to have a README.rdoc without backslashes for
+ # GitHub, and gsub it to generate the main page of the API.
+ #
+ # The idea for the future is to have totally different files, since the
+ # API is no longer a generic entry point to Rails and deserves a
+ # dedicated main page specifically thought as an API entry point.
rdoc.before_running_rdoc do
rdoc_main = File.read('README.rdoc')
- rdoc_main.gsub!(/\b(?=Rails)\b/) { '\\' }
+
+ # The ^(?=\S) assertion prevents code blocks from being processed,
+ # since no autolinking happens there and RDoc displays the backslash
+ # otherwise.
+ rdoc_main.gsub!(/^(?=\S).*?\b(?=Rails)\b/) { "#$&\\" }
+
File.open(RDOC_MAIN, 'w') do |f|
f.write(rdoc_main)
end

0 comments on commit e51b8fb

Please sign in to comment.
Something went wrong with that request. Please try again.