|Version 15 (modified by cho45, 6 years ago)|
Resh - a light template for RDoc
Resh is a HTML template for RDoc.
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/
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
- Use ERB instead of rdoc/template.
- Throw framesets out the window.
- Be careful about colors.
- Think about information design. (especially information of index page)
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.
- 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)