NOTE I abandoned this project. Do not use this if you don’t want to maintain it yourself!

You think Darkfish is the worst RDoc generator ever? Got lost in SDoc and Horo documentations? Found Hanna buggy and dislike frames? Then this is for you: Emerald, the only RDoc template which makes your Ruby docs a jewel, too.

Emerald is a generator for RDoc, i.e. a plugin that replaces RDoc’s standard Darkfish generator from which many people (myself included) think it’s the ugliest RDoc layouting engine that ever was around. If you want nice and modern documentation that allows you to retain overview over a library, Emerald is the generator you want to use.

Emerald is currently Alpha software. Use it at your own risk.

Get the current development release via RubyGems:

# gem install emerald --pre

If you want the latest version, check out the Git repisitory and build the gem yourself:

$ git clone git://github.com/Quintus/emerald
$ cd emarald
$ rake gem
$ gem install pkg/emerald-x.x.x.gem

From the commandline:

$ rdoc -f emerald YOURFILESHERE

From a rake RDoc::Task:

require "rdoc/task"
require "rdoc/generator/emerald"

RDoc::Task.new do |rt|
  # Your option stuff...
  rt.generator = "emerald"
end

• Default theme has is centered around light blue/grey, just as Hanna was.

• No frames.

• Uses jQuery.

• Generates a Table of Contents (ToC) for toplevel file docs (so yes, your README will have a ToC).

• Classical file/class/method indices for best overview.

• Regular-Expression-powered JavaScript search.

• Darkfish-link compatible, i.e. if you switch to Emerald from Darkfish, the old links to your documentation will still work.

  • But note this is not the case for the other way round, as Emerald allows you linking to more stuff.

• GPL’ed. Free software.

• And more…

• Sourcecode: github.com/Quintus/emerald

• Bugtracker: github.com/Quintus/emerald/issues

• ToC generation only works for proper heading nestings, especially it assumes your page to have exactly one level-1 heading. Having more of these is bad style, and Emerald wants to encourage good documentation/markup style.

• The search uses JavaScript’s regular expressions, so the quite advanced constructs you can create with Ruby’s Regular Expressions won’t work with all cases. But don’t tell me you search your API documentation with constructs like \A(?>[^ab]q)\s*%.*stuff(?<!badstuff)\w{2,4}(?:$|\\).

• Emerald is a bit slow at the moment. However, I did not optimise it for speed. This may or may not change in the future.

Thanks to Eric Hodel keeping RDoc in an active and alive state. Without this, there would be no point in developing Emerald. Next my gratitude is dedicated at Mislav Marohnić for creating the Hanna RDoc template, which sadly is not maintained anymore, but was a big inspiration for Emerald and its default theme, and to everyone on the web who posted something on RDoc’s internals. Without you, it wouldn’t have been possible to get Emerald to where it currently is.

Emerald is an RDoc HTML generator.

Copyright © 2013 Marvin Gülker

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <www.gnu.org/licenses/>.

• You can find the GNU GPL in the file COPYING.rdoc.

• This project incorporates some code and data (mainly images) from RDoc and the projects RDoc in turn uses stuff from. See the file LEGAL.rdoc for more information. Same goes for the jQuery licensing conditions.

• You can contact me at quintus ÄT quintilianus DÖT eu.