Resh - a light template for RDoc

Resh is a HTML template for RDoc.

Samples

• http://safeeval.rubyforge.org/
• http://modulepluggable.rubyforge.org/
• http://osxhotkey.rubyforge.org/

Download

svn co http://svn.coderepos.org/share/lang/ruby/rdoc/generators/template/html/resh/

Usage

Using Resh with your local gems documentation

Edit ~/.gemrc to customize rdoc template. File format of this file is YAML, so you have to be careful about linefeed code etc.

rdoc: --template path-to/resh.rb

Then run following command:

sudo gem rdoc --all --no-ri --config-file ~/.gemrc

This command re-generates all RDoc of local gems using the config-file as option.

Using your gem to publish on-line documentation

You can also use Resh for your gems documentations by setting the option of Rake::RDocTask in your Rakefile.

Rake::RDocTask.new do |rdoc|
	rdoc.rdoc_dir = 'html'
	rdoc.options += RDOC_OPTS
	rdoc.template = "path-to/resh.rb" # path to your checkouted resh.rb
	if ENV['DOC_FILES']
		rdoc.rdoc_files.include(ENV['DOC_FILES'].split(/,¥s*/))
	else
		rdoc.rdoc_files.include('README', 'Changelog')
		rdoc.rdoc_files.include('examples/simple.rb')
		rdoc.rdoc_files.include('lib/**/*.rb')
		rdoc.rdoc_files.include('ext/**/*.c')
	end
end

Concepts

• Use ERB instead of rdoc/template.
• Throw framesets out the window.
• Be careful about colors.
• Think about information design. (especially information of index page)

Internals

The html_generator.rb (may be in /usr/lib/ruby/1.8/rdoc/generators) in RDoc is using rdoc/template as template engine, but ruby has ERB great template engine, so I want to also use ERB as RDoc template. (I hate the template languages which has different syntax from host languages.)

Resh uses ERB by overwriting a portion of Generator::Html* methods. For Example:

class ::Generators::HtmlClass
	def write_on(f)
		return unless defined? RDoc::Page::CLASS_PAGE
		value_hash
#		template = TemplatePage.new(RDoc::Page::BODY,
#									RDoc::Page::CLASS_PAGE,
#									RDoc::Page::METHOD_LIST)
#		template.write_html_on(f, @values)
		values = @values
		f << ERB.new(File.read($tmpl+RDoc::Page::CLASS_PAGE)).result(binding)
	end
end

load_html_template in html_generator loads template by require and it is processed before any template processing.

This way is fragile but powerful. I love ruby because of allowing these ways.

Other stuff

• Vox entry: New fresh RDoc template for all rubyist. - Vox of a clumsy sugar.

Resh is abbreviation of reshape and pronounce as le'∫. (This is Engrish)