RubyGems - emerald - Versions diffs - 0.0.1.alpha1 - Mend

emerald 0.0.1.alpha1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

data/CHANGELOG.rdoc +7 -0
data/COPYING.rdoc +664 -0
data/LEGAL.rdoc +140 -0
data/README.rdoc +115 -0
data/VERSION +1 -0
data/data/images/tag_blue.png +0 -0
data/data/images/zoom.png +0 -0
data/data/javascripts/emerald.js +115 -0
data/data/javascripts/jquery.js +2 -0
data/data/javascripts/toc.js +52 -0
data/data/templates/classmodule.html.erb +99 -0
data/data/templates/layout.html.erb +80 -0
data/data/templates/toplevel.html.erb +13 -0
data/lib/rdoc/discover.rb +4 -0
data/lib/rdoc/generator/emerald.rb +260 -0
data/lib/rdoc/generator/emerald/options.rb +37 -0
metadata +106 -0

data/data/templates/layout.html.erb ADDED

@@ -0,0 +1,80 @@
+<!DOCTYPE HTML>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+    <link rel="stylesheet" type="text/css" href="<%= root_path + 'stylesheets' + 'rdoc.css' %>"/>
+    <script src="<%= root_path + 'javascripts' + 'jquery.js' %>"></script>
+    <script src="<%= root_path + 'javascripts' + 'emerald.js' %>"></script>
+    <script src="<%= root_path + 'javascripts' + 'toc.js' %>"></script>
+    <title><%= title %></title>
+  </head>
+  <body>
+    <div id="indices">
+      <form id="search">
+        <p style="margin-top: 0px"><input style="width: 100%" type="text" placeholder="Regexp Search"/></p>
+      </form>
+      <div class="index" id="file-index">
+        <div class="header">
+          <p>File Index</p>
+        </div>
+        <ul>
+          <% @toplevels.each do |tl| %>
+            <% target = root_path + rdocize_toplevel(tl) %>
+            <% if tl.name.end_with?(".rdoc") %>
+              <li class="rdoc-file"><a href="<%= target %>"><%= tl.name %></a></li>
+            <% else %>
+              <%# Usually you don’t want to see the code files %>
+              <li class="code-file" style="display: none"><a href="<%= target %>"><%= tl.name %></a></li>
+            <% end %>
+          <% end %>
+          <li><a style="font-style: italic" id="toggle-all-files" href="#">Show all</a></li>
+        </ul>
+      </div>
+      <div class="index" id="class-index">
+        <div class="header">
+          <p>Class Index</p>
+        </div>
+        <ul>
+          <% @classes_and_modules.each do |classmod| %>
+            <li>
+              <a href="<%= root_path + rdocize_classmod(classmod) %>"><%= classmod.full_name %></a>
+            </li>
+          <% end %>
+        </ul>
+      </div>
+      <div class="index" id="method-index">
+        <div class="header">
+          <p>Method Index</p>
+        </div>
+        <ul>
+          <% @methods.each do |method| %>
+            <li><a href="<%= root_path +
+          "#{rdocize_classmod(method.parent)}##{method.aref}"
+          %>"><%= method.pretty_name %></a>&nbsp;<span class="method-classname">(<%= method.parent.full_name %>)</span></li>
+          <% end %>
+        </ul>
+      </div>
+    </div>
+    <div id="content">
+      <%= yield %>
+      <div id="footer">
+        <p style="width: 49%; float: left">Time: <%= Time.now %></p>
+        <p style="width: 49%; float: right; text-align: right">
+          Generated by
+          <a href="https://github.com/Quintus/emerald">
+            Emerald generator for RDoc
+          </a>
+        </p>
+      </div>
+    </div>
+    <div class="clear"></div>
+  </body>
+</html>

data/data/templates/toplevel.html.erb ADDED

@@ -0,0 +1,13 @@
+<p class="toplevel-name"><%= toplevel.full_name %></p>
+<%= toplevel.description %>
+<% if @options.generate_toc %>
+  <script>
+    html = "<div class=\"toc\"><p>Contents</p>";
+    html += generate_toc();
+    html += "</div>";
+    $(html).insertAfter("h1");
+  </script>
+<% end %>

data/lib/rdoc/discover.rb ADDED

@@ -0,0 +1,4 @@
+# Discovery file for RDoc to recognise this
+# generator.
+require_relative "generator/emerald"

data/lib/rdoc/generator/emerald.rb ADDED

@@ -0,0 +1,260 @@
+# -*- coding: utf-8 -*-
+gem "rdoc"
+require "pathname"
+require "fileutils"
+require "erb"
+require "rdoc/rdoc"
+require "rdoc/generator"
+# 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 <b>data/templates</b> 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, <b>data/templates/layout.html.erb</b>, 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 <b>../</b> 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.
+class RDoc::Generator::Emerald
+  include FileUtils
+  # Generic exception class for this generator.
+  class EmeraldError < StandardError
+  end
+  # Tell RDoc about the new generator
+  RDoc::RDoc.add_generator(self)
+  # Description displayed in RDoc’s help.
+  DESCRIPTION = "The only RDoc generator that makes your Ruby documentation a jewel, too"
+  # Root directory of this project.
+  ROOT_DIR = Pathname.new(__FILE__).dirname.parent.parent.parent
+  # Where to find the non-code stuff.
+  DATA_DIR = ROOT_DIR + "data"
+  # Main template used as the general layout.
+  LAYOUT_TEMPLATE = ERB.new(File.read(DATA_DIR + "templates" + "layout.html.erb"))
+  # Subtemplates injected into the main template.
+  TEMPLATES = {
+    :toplevel    => ERB.new(File.read(DATA_DIR + "templates" + "toplevel.html.erb")),
+    :classmodule => ERB.new(File.read(DATA_DIR + "templates" + "classmodule.html.erb"))
+  }
+  # The version number.
+  VERSION = File.read(ROOT_DIR + "VERSION").chomp.freeze
+  # Add additional options to RDoc (see the
+  # RDoc::Generator::Emerald::Options module).
+  def self.setup_options(options)
+    options.extend(RDoc::Generator::Emerald::Options)
+  end
+  class << self
+    protected
+    # Protected foo.
+    def foo
+    end
+    private
+    # Private bar.
+    def bar
+    end
+  end
+  # Instanciates this generator. Automatically called
+  # by RDoc.
+  # ==Parameter
+  # [options]
+  #   RDoc passed the current RDoc::Options instance.
+  def initialize(options)
+    @options = options
+    @op_dir = Pathname.pwd.expand_path + @options.op_dir
+  end
+  def generate(top_levels)
+    @toplevels = top_levels
+    @classes_and_modules = RDoc::TopLevel.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
+      File.open(@op_dir + "index.html", "w") do |file|
+        file.write("<!DOCTYPE HTML>\n<html><head><title>RDoc documentation</title></head><body><p>This is the RDoc documentation.</p></body></html>")
+      end
+    end
+  end
+  # Darkfish returns +nil+, hence we do this as well.
+  def file_dir
+    nil
+  end
+  # Darkfish returns +nil+, hence we do this as well.
+  def class_dir
+    nil
+  end
+  protected
+  # Set/get the root directory.
+  # == Parameter
+  # [set_to (nil)]
+  #   If passed, this method _sets_ the root directory rather
+  #   than returning it.
+  # == Return value
+  # The current relative path to the root directory.
+  # == Remarks
+  # See the class’ introductory text for more information
+  # on this.
+  def root_path(set_to = nil)
+    if set_to
+      @root_path = Pathname.new(set_to)
+    else
+      @root_path ||= Pathname.new("./")
+    end
+  end
+  # Set/get the page title.
+  # == Parameter
+  # [set_to (nil)]
+  #   If passed, this method _sets_ the title rather
+  #   than returning it.
+  # == Return value
+  # The current page title.
+  # == Remarks
+  # Works the same way as #root_path.
+  def title(set_to = nil)
+    if set_to
+      @title = set_to
+    else
+      @title ||= ""
+    end
+  end
+  # Takes a RDoc::TopLevel and transforms it into a complete pathname
+  # relative to the output directory. Filename alterations
+  # done by RDoc’s crossref-HTML formatter are honoured. Note you
+  # have to prepend #root_path to get a complete href.
+  def rdocize_toplevel(toplevel)
+    Pathname.new("#{toplevel.relative_name.gsub(".", "_")}.html")
+  end
+  # Takes a RDoc::ClassModule and transforms it into a complete pathname
+  # relative to the output directory. Filename alterations
+  # done by RDoc’s crossref-HTML formatter are honoured. Note you
+  # have to prepend #root_path to get a complete href.
+  def rdocize_classmod(classmod)
+    Pathname.new(classmod.full_name.split("::").join("/") + ".html")
+  end
+  private
+  def copy_base_files
+    mkdir @op_dir + "stylesheets" unless File.directory?(@op_dir + "stylesheets")
+    cp   Dir[DATA_DIR + "stylesheets" + "*.css"], @op_dir + "stylesheets"
+    cp_r DATA_DIR + "javascripts", @op_dir
+    cp_r DATA_DIR + "images",      @op_dir
+  end
+  def evaluate_toplevels
+    @toplevels.each do |toplevel|
+      root_path("../" * (toplevel.relative_name.split("/").count - 1)) # Last component is a filename
+      title toplevel.relative_name
+      # Create the path to the file if necessary
+      path = @op_dir + rdocize_toplevel(toplevel)
+      mkdir_p path.parent unless path.parent.exist?
+      # Evaluate the actual file documentation
+      File.open(path, "w") do |file|
+        file.write(render(:toplevel, binding))
+      end
+      # If this toplevel is supposed to be the main file,
+      # copy it’s content to the index.html file.
+      if toplevel.relative_name == @options.main_page
+        root_path "./" # We *are* at the top here
+        File.open(@op_dir + "index.html", "w") do |file|
+          file.write(render(:toplevel, binding))
+        end
+      end
+    end
+  end
+  def evaluate_classes_and_modules
+    @classes_and_modules.each do |classmod|
+      path = @op_dir + rdocize_classmod(classmod)
+      mkdir_p   path.parent unless path.parent.directory?
+      title     classmod.full_name
+      root_path "../" * (classmod.full_name.split("::").count - 1) # Last element is a file
+      File.open(path, "w") do |file|
+        file.write(render(:classmodule, binding))
+      end
+    end
+  end
+  # Renders the subtemplate +template_name+ in the +context+ of the
+  # given binding, then injects it into the main template (which is
+  # evaluated in the same +context+).
+  #
+  # Returns the resulting string.
+  def render(template_name, context)
+    render_into_layout{TEMPLATES[template_name].result(context)}
+  end
+  # Renders into the main layout. The return value of the block
+  # passed to this method will be placed in the layout in place
+  # of the +yield+ expression.
+  def render_into_layout
+    LAYOUT_TEMPLATE.result(binding)
+  end
+end
+require_relative "emerald/options"

data/lib/rdoc/generator/emerald/options.rb ADDED

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+# This mixin module contains the extra options Emerald
+# adds to the default RDoc ones. It is used in the
+# RDoc::Generator::Emerald::setup_options method.
+module RDoc::Generator::Emerald::Options
+  # Tells RDoc’s OptionParser about the new options when
+  # the RDoc::Options object is extended with this mixin.
+  def self.extended(options)
+    op = options.option_parser
+    op.separator ""
+    op.separator "Emerald generator options:"
+    op.separator ""
+    op.on("--[no-]generate-toc",
+          "Enables or disables generation of the",
+          "table of contents (ToC) for toplevel files."){|val| options.generate_toc = val}
+  end
+  # Whether or not to generate a Table of Contents (ToC) for
+  # toplevel files. Defaults to true.
+  #
+  # Note that the mechanism is implemented in JavaScript,
+  # which has therefore to be enabled in your browser.
+  def generate_toc
+    @generate_toc = true unless defined?(@generate_toc)
+    @generate_toc
+  end
+  # Setter for #generate_toc.
+  def generate_toc=(val)
+    @generate_toc = val
+  end
+end

metadata ADDED

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: emerald
+version: !ruby/object:Gem::Version
+  version: 0.0.1.alpha1
+  prerelease: 6
+platform: ruby
+authors:
+- Marvin Gülker
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2012-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: sass
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+description: ! 'Emerald is a generator for RDoc, like standard Darkfish, but looks
+  much better (and does not have this touch of green). It is inspired
+  by Hanna, but does not share any code with it (and does not use frames!).
+'
+email: quintus@quintilianus.eu
+executables: []
+extensions: []
+extra_rdoc_files:
+- COPYING.rdoc
+- LEGAL.rdoc
+- CHANGELOG.rdoc
+- README.rdoc
+files:
+- lib/rdoc/discover.rb
+- lib/rdoc/generator/emerald/options.rb
+- lib/rdoc/generator/emerald.rb
+- COPYING.rdoc
+- LEGAL.rdoc
+- CHANGELOG.rdoc
+- README.rdoc
+- data/javascripts/toc.js
+- data/javascripts/jquery.js
+- data/javascripts/emerald.js
+- data/images/zoom.png
+- data/images/tag_blue.png
+- data/templates/layout.html.erb
+- data/templates/classmodule.html.erb
+- data/templates/toplevel.html.erb
+- VERSION
+homepage: https://github.com/Quintus/emerald
+licenses: []
+post_install_message:
+rdoc_options:
+- -t
+- Emerald RDocs
+- -m
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '1.9'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project:
+rubygems_version: 1.8.24
+signing_key:
+specification_version: 3
+summary: The only RDoc generator that makes your Ruby documentation a jewel, too
+test_files: []