Making an RDoc Template Gem

tcsnide · October 1, 2009, 6:55am

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?

Thanks.

tcsnide · October 1, 2009, 7:34pm

On Wed, Sep 30, 2009 at 11:53 PM, Intransition [email protected]
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?

Thanks.

I think the best way to do it is as an rdoc plugin. RDoc_chm[1] is an
RDoc plugin to. RDoc searches for lib/rdoc/discover.rb in gems, and
loads them. You have to have a require in discover.rb. This will add
your gem’s lib and bin to $LOAD_PATH. I’m not totally sure how that
works, if it’s a feature of RubyGems, or RDoc. If you have no ruby
code in your template, you can just use “require ‘rdoc/discover’”.
The Darkfish generator searches for a template dir of the name
provided on the command line. If no template is given, it defaults to
the name of the generator.

Say your template is called macguffin, you’d put your template code in
lib/rdoc/generator/template/macguffin. When rdoc is run with
–template=macguffin, it will search each dir in $LOAD_PATH for dir +
/rdoc/generator/template/macguffin

Hope that makes sense.

[1] GitHub - vertiginous/rdoc_chm: A Microsoft Compiled HTML Help generator for RDoc.

tcsnide · October 1, 2009, 8:00pm

On Oct 1, 12:53 am, Intransition [email protected] 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.

tcsnide · October 2, 2009, 1:09am

Hi again—

On Oct 1, 1:32 pm, Gordon T. [email protected] wrote:

I think the best way to do it is as an rdoc plugin. RDoc_chm[1] is an
RDoc plugin to. RDoc searches for lib/rdoc/discover.rb in gems, and
loads them. You have to have a require in discover.rb. This will add
your gem’s lib and bin to $LOAD_PATH. I’m not totally sure how that
works, if it’s a feature of RubyGems, or RDoc. If you have no ruby
code in your template, you can just use “require ‘rdoc/discover’”.
The Darkfish generator searches for a template dir of the name
provided on the command line. If no template is given, it defaults to
the name of the generator.

Unfortunately the discover.rb thing does not work. I’m not sure what
RDoc is doing --it doesn’t seem like it is doing anything in this
regard actually. To get my RDoc to discover my template I somehow have
to run:

gem ‘rdazzle’

So it will be on the #LOAD_PATH. The only place to do that is say a
Rakefile and use rake to generate the rdocs, or to add RUBYTOPT=“-
rrdazzle”.

Not to mention a couple options seem busted.

RDoc needs some work.

~Trans.

tcsnide · October 1, 2009, 8:02pm

On Oct 1, 1:32 pm, Gordon T. [email protected] wrote:

loads them. You have to have a require in discover.rb. This will add
/rdoc/generator/template/macguffin
Ha! You must have wrote your response the same time I was writing
mine! Go figure!

Hope that makes sense.

It does make sense. Thank You!

[1]GitHub - vertiginous/rdoc_chm: A Microsoft Compiled HTML Help generator for RDoc.

Ah, that makes all the difference. I got pretty close figuring it out
my own. This will help me tweak my code to get it exact. Big thanks
again.

tcsnide · October 2, 2009, 3:59am

On Oct 1, 7:06 pm, trans [email protected] wrote:

The Darkfish generator searches for a template dir of the name
So it will be on the #LOAD_PATH. The only place to do that is say a
Rakefile and use rake to generate the rdocs, or to add RUBYTOPT=“-
rrdazzle”.

Final follow-up on this. I verified that indeed discover.rb is being
loaded, but to get my template to be located I had to add:

gem ‘rdazzle’

to the top of the discover.rb file. Why the require wan;t enough I
don’t know. But the gem call seemed to do the trick. Note that using:

gem ‘rdoc’, “>= 2.4”

in the subsequently required file (i.e. where the subclass of Darkfish
is defined) caused some error for RubyGems. Is RubyGems dependent on
2.3 series? In any case I just omitted that whole file for now.

Thanks for the help, and I hope this thread might be helpful to others
if they want to create their own RDOC template plugins.

T.