From caadef9dd4107cfc98eb237a23db8a4a158c2c3c Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 12 Jun 2011 15:03:28 +0200 Subject: backslash insertion for RDoc main page ignores code blocks, also adds comments to explain what's this hack about --- Rakefile | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'Rakefile') diff --git a/Rakefile b/Rakefile index cffa0ae80d..ba55e580f4 100755 --- a/Rakefile +++ b/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 -- cgit v1.2.3