Class: RDoc::Generator::Emerald

Inherits:
Object
  • Object
show all
Includes:
FileUtils
Defined in:
lib/rdoc/generator/emerald.rb

Overview

This is the main generator class that is instanciated by RDoc when you order it to use the emerald generator. It mainly works on ERB template files you can find in the data/templates directory, where each major component (read: classes and toplevel files) has a template file that is evaluated for it. The result is then injected into the layout template, data/templates/layout.html.erb, which is then evaluated as well.

About relative paths

As the output generated by RDoc is supposed to be viewable by both visiting the doc/ directory with a browser and providing the doc/ directory to an HTTP server, effectively making it the root directory, care has been taken to only use relative links in all the static HTML files. The key component for this to work is the #root_path method, which is called to set the relative path to the root directory (i.e. the output directory). When called without an argument, #root_path returns the value previously remembered (usually it contains a good number of ../ entries). This way, the root directory can be set whenever a new HTML file is going to be outputted and can then be referenced from the ERB template.

Darkfish compatibility

RDoc’s HTML formatter has a good number of helper methods that have a strong hint regarding “where what belongs”. By using these helper methods itself when creating cross-references, the HTML formatter enforces both the directory structure of the output directory and the anchor names used for references inside a single HTML file. The only way to circumvent this is to write another formatter, which I don’t intend to as the standard HTML formatter does a good job for HTML stuff. A nice side effect is that Emerald’s documentation is compatible with Darkfish’s one when it comes to links to specific elements. For example, you can create a link to a method called Foo::Bar#baz somewhere on the web, and if the destinatinon website chooses to switch from Darkfish output to Emerald (which I hope!), the link will continue to work.

Defined Under Namespace

Classes: DummyStartPage, EmeraldError

Constant Summary collapse

DESCRIPTION =

Description displayed in RDoc’s help.

"The only RDoc generator that makes your Ruby documentation a jewel, too"
ROOT_DIR =

Root directory of this project.

Pathname.new(__FILE__).dirname.parent.parent.parent
DATA_DIR =

Where to find the non-code stuff.

ROOT_DIR + "data"
LAYOUT_TEMPLATE =

Main template used as the general layout.

ERB.new(File.read(DATA_DIR + "templates" + "layout.html.erb"))
TEMPLATES =

Subtemplates injected into the main template.

{
  :toplevel    => ERB.new(File.read(DATA_DIR + "templates" + "toplevel.html.erb")),
  :classmodule => ERB.new(File.read(DATA_DIR + "templates" + "classmodule.html.erb"))
}
VERSION =

The version number.

File.read(ROOT_DIR + "VERSION").chomp.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(store, options) ⇒ Emerald

Instanciates this generator. Automatically called by RDoc.

Parameter

options

RDoc passed the current RDoc::Options instance.



129
130
131
132
133
 
# File 'lib/rdoc/generator/emerald.rb', line 129

def initialize(store, options)
  @store   = store
  @options = options
  @op_dir  = Pathname.pwd.expand_path + @options.op_dir
end

Class Method Details

.setup_options(options) ⇒ Object

Add additional options to RDoc (see the RDoc::Generator::Emerald::Options module).



120
121
122
 
# File 'lib/rdoc/generator/emerald.rb', line 120

def self.setup_options(options)
  options.extend(RDoc::Generator::Emerald::Options)
end

Instance Method Details

#class_dir ⇒ Object

Darkfish returns nil, hence we do this as well.



170
171
172
 
# File 'lib/rdoc/generator/emerald.rb', line 170

def class_dir
  nil
end

#debug(str) ⇒ Object

Outputs a string on standard output, but only if RDoc was invoked with the --debug switch.



137
138
139
 
# File 'lib/rdoc/generator/emerald.rb', line 137

def debug(str)
  puts(str) if $DEBUG_RDOC
end

#file_dir ⇒ Object

Darkfish returns nil, hence we do this as well.



165
166
167
 
# File 'lib/rdoc/generator/emerald.rb', line 165

def file_dir
  nil
end

#generate ⇒ Object

Main hook method called by RDoc, triggers the generation process.



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/rdoc/generator/emerald.rb', line 142

def generate
  debug "Sorting classes, modules, and methods..."
  @toplevels = @store.all_files
  @classes_and_modules = @store.all_classes_and_modules.sort_by{|klass| klass.full_name}
  @methods = @classes_and_modules.map{|mod| mod.method_list}.flatten.sort

  # Create the output directory
  mkdir @op_dir unless @op_dir.exist?

  copy_base_files
  evaluate_toplevels
  evaluate_classes_and_modules

  unless @options.main_page # If set, #evaluate_toplevels creates the index.html for us
    toplevel = DummyStartPage.new
    root_path "./" # This *is* in the toplevel
    File.open(@op_dir + "index.html", "w") do |file|
      file.write(render(:toplevel, binding))
    end
  end
end