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:
arkfish
RDoc::RDoc.add_generator( self )
include ERB::Util
# Subversion rev
SVNRev =3D %$Rev: 52 $
# Subversion ID
SVNId =3D %$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 =3D File.join 'rdoc', 'generator'
# Release Version
VERSION =3D '1.1.6'
# Directory where generated classes live relative to the root
CLASS_DIR =3D nil
# Directory where generated files live relative to the root
FILE_DIR =3D 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 =3D options
@options.diagram =3D false
template =3D @options.template || 'darkfish'
template_dir =3D $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 =3D Pathname.new File.expand_path(template_dir)
@files =3D nil
@classes =3D nil
@basedir =3D 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.
