How do I customize the rdoc Darkfish stylesheet?

Question

I'm using Rake to generate RDoc documentation for my project, but I really hate the gray-on-gray style that Darkfish seems to generate. I'm happy with everything else, I'd just like to make the color scheme a little more readable.

Here's my rake task:

Rake::RDocTask.new do |rd|
    rd.main = "README.rdoc"
    rd.title = "My Title"
    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
    rd.options = ['--main', 'README.rdoc']
end

I've tried adding '--style', 'doc/rdoc.css' to the rd.options above, but it complains that --style is an unknown option and ignores it. I can't seem to find any documentation on how to customize templates or css etc; do I just have to put up with what Darkfish thinks looks good?

score 1 · Answer 1 · answered Apr 07 '11 at 02:05

If you look at the Darkfish templates, the only CSS references you'll see are things like this:

<link type="text/css" media="screen" href="<%= rel_prefix %>/rdoc.css" rel="stylesheet" />

Some of them have the rel_prefix and some don't. There's nothing in any of the templates for including other stylesheets. Presumably, you should just apply your coloring changes to rdoc.css or hand-edit the templates to include another stylesheet with your modifications.

A better approach would be to patch --style support into Darkfish and send the author a patch. Looks like you'd just need to add a small bit of extra erb to the templates, some switch parsing logic, and a new variable around calls to self.render_template in lib/rdoc/generator/darkfish.rb. Sounds like this would be a useful addition to Darkfish, the author might even be pleased that someone wants to make his software better.

score 1 · Answer 2 · answered Mar 02 '12 at 02:05

1

Can't you just grab the copy of the .css file that darkfish generates, then make your modifications, and store it in a separate directory on your hard disk. Then in your rake task, just overwite the .css file when rdoc is done?

answered Mar 02 '12 at 02:05

user1182000

1,625
14
12

score 0 · Accepted Answer · answered Apr 08 '11 at 14:56

Darkfish has template support with --template 'your_template_name'; which will need to be set up as a an rdoc plugin gem, i believe.

This might help as well: http://fossplanet.com/f14/making-rdoc-template-gem-26986/

An RDoc plugin gem meaning a gem with a directory structure like:

./lib/rdoc/generator/template/#{your template name and files copied from rdoc-2.blah/lib/rdoc/generator/template/darkfish}

and

./rdoc/generate.rb prepending the above template directory to the $LOAD_PATH. ($LOAD_PATH.unshift(File.expand_path(File.join(Dir.pwd,'..','lib', "#{..... and so on}")

How do I customize the rdoc Darkfish stylesheet?

3 Answers3