Resh - a light template for RDoc

Resh is a HTML template for RDoc.

Samples

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

Download/Install

If you use resh only with gems, you can use gem install:

sudo gem install resh

In this case, rdoc --template resh may not be worked because of not loading gems. This works only in Rake::RDocTask#template or ~/.gemrc or RUBYOPT="-rubygems" in environment.

If you want to install to given place, use svn:

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 resh

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 Resh for publishing on-line documentation of your gem

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 = "resh"
	# rdoc.template = "path-to/resh.rb" # or 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.
• Subtech: RDoc テンプレート Resh

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