From: trans <transfire@...>
Date: 2009-10-02T02:55:17+09:00
Subject: Re: Making an RDoc Template Gem



On Oct 1, 12:53 am, Intransition <transf...@gmail.com> wrote:
> I want to create a new RDoc template and I want to ship it as a gem.
> But I cannot figure out how to set it up so RDoc will find it. For
> that matter I'm not exactly sure what kind of file it's wants either.
> Is there any documentation on this anywhere?

Following up to my own question, b/c for some reason the most
important piece of supplementary Ruby code in existence is far too
under supported and developed... Of course, I am thankful that Eric
has taken some time to work on it at all. I see there are two rdoc
forks on GitHub, voloko and wycats. Perhaps if we could get an
official repo on GitHub and merge them all together it would help?
Anyhow...

The key to my question is in this code:

  class RDoc::Generator::Darkfish

	RDoc::RDoc.add_generator( self )

	include ERB::Util

	# Subversion rev
	SVNRev = %$Rev: 52 $

	# Subversion ID
	SVNId = %$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $

	# Path to this file's parent directory. Used to find templates and
other
	# resources.
	GENERATOR_DIR = File.join 'rdoc', 'generator'

	# Release Version
	VERSION = '1.1.6'

	# Directory where generated classes live relative to the root
	CLASS_DIR = nil

	# Directory where generated files live relative to the root
	FILE_DIR = nil

	#################################################################
	###	C L A S S   M E T H O D S
	#################################################################

	### Standard generator factory method
	def self::for( options )
		new( options )
	end

	#################################################################
	###	I N S T A N C E   M E T H O D S
	#################################################################

	### Initialize a few instance variables before we start
	def initialize( options )
		@options = options
		@options.diagram = false

		template = @options.template || 'darkfish'

		template_dir = $LOAD_PATH.map do |path|
			File.join path, GENERATOR_DIR, 'template', template
		end.find do |dir|
			File.directory? dir
		end

		raise RDoc::Error, "could not find template #{template.inspect}"
unless
			template_dir

		@template_dir = Pathname.new File.expand_path(template_dir)

		@files      = nil
		@classes    = nil

		@basedir = Pathname.pwd.expand_path
	end

Why the HTML formatter is called Darkfish, well.. it is what it is. So
the trick is create a directory in the $LOAD_PATH 'rdoc/generator/
template/{name}/' with files:

  classpage.rhtml
  filepage.rhtml
  index.rhtml
  rdoc.css
  images/
  js/


The .html files are the important ones (the others are simply
referenced by them). If you're distributing this as a gem, the hard
part is to make sure the directory is getting in the LOAD_PATH, so
somehow

  gem 'name'

has to be invoked for rdoc to find the template.

As for replacing the formatter itself... thats' something I haven't
dug into and hopefully won't need to, but we shall see b/c I'm
thinking I'd like to use Coderay for syntax highlighting --that will
surely require it.

Yours.