# Making an RDoc Template Gem **URL:** \ **Category:** Ruby\ **Created:** [October 1, 2009, 6:55am UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482 "2009-10-01T06:55:41Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\ **Post date:** [October 1, 2009, 6:55am UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482/1 "2009-10-01T06:55:41Z")
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. ---
**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\ **Post date:** [October 1, 2009, 7:34pm UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482/2 "2009-10-01T19:34:24Z")
On Wed, Sep 30, 2009 at 11:53 PM, Intransition [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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.](https://github.com/vertiginous/rdoc_chm) ---
**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\ **Post date:** [October 1, 2009, 8:00pm UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482/3 "2009-10-01T20:00:45Z")
On Oct 1, 12:53 am, Intransition [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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. ---
**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\ **Post date:** [October 2, 2009, 1:09am UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482/4 "2009-10-02T01:09:15Z")
Hi again— On Oct 1, 1:32 pm, Gordon T. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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. ---
**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\ **Post date:** [October 1, 2009, 8:02pm UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482/5 "2009-10-01T20:02:30Z")
On Oct 1, 1:32 pm, Gordon T. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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.](https://github.com/vertiginous/rdoc_chm) 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. ---
**Author:** ![tcsnide](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/t/eb8c5e/32.png) [@tcsnide](https://www.ruby-forum.com/u/tcsnide)\ **Post date:** [October 2, 2009, 3:59am UTC](https://www.ruby-forum.com/t/making-an-rdoc-template-gem/176482/6 "2009-10-02T03:59:03Z")
On Oct 1, 7:06 pm, trans [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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.