emerald 0.0.1.alpha3 → 0.0.1.alpha4

data/pkg/emerald-0.0.1.alpha4/LEGAL.rdoc

@@ -0,0 +1,140 @@
+= Legal stuff
+
+Emerald uses some code from RDoc (currently maintained by Eric Hodel)
+and it’s Darkfish generator (written by Michael Granger) as well as
+some of Darkfish’s iconset, which in turn was taken from the Silk
+iconset by Mark James. See below for all those copying conditions.
+
+For Emerald’s own licensing conditions, see the file COPYING.rdoc.
+
+== RDoc license
+
+RDoc is copyrighted free software.
+
+You can redistribute it and/or modify it under either the terms of the GPL
+version 2 (see the file GPL), or the conditions below:
+
+1. You may make and give away verbatim copies of the source form of the
+   software without restriction, provided that you duplicate all of the
+   original copyright notices and associated disclaimers.
+
+2. You may modify your copy of the software in any way, provided that
+   you do at least ONE of the following:
+
+   a. place your modifications in the Public Domain or otherwise
+      make them Freely Available, such as by posting said
+      modifications to Usenet or an equivalent medium, or by allowing
+      the author to include your modifications in the software.
+
+   b. use the modified software only within your corporation or
+      organization.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+3. You may distribute the software in object code or binary form,
+   provided that you do at least ONE of the following:
+
+   a. distribute the binaries and library files of the software,
+      together with instructions (in the manual page or equivalent)
+      on where to get the original distribution.
+
+   b. accompany the distribution with the machine-readable source of
+      the software.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+4. You may modify and include the part of the software into any other
+   software (possibly commercial).  But some files in the distribution
+   are not written by the author, so that they are not under these terms.
+
+   For the list of those files and their copying conditions, see the
+   file LEGAL[http://rdoc.rubyforge.org/LEGAL_rdoc.html].
+
+5. The scripts and library files supplied as input to or produced as
+   output from the software do not automatically fall under the
+   copyright of the software, but belong to whomever generated them,
+   and may be sold commercially, and may be aggregated with this
+   software.
+
+6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   PURPOSE.
+
+== Darkfish license
+
+Darkfish was written by Michael Granger and is included under the MIT
+license. Darkfish contains images from the Silk Icons set by Mark
+James.
+
+=== Author/s
+* Michael Granger (ged@FaerieMUD.org)
+
+=== Contributors
+* Mahlon E. Smith (mahlon@martini.nu)
+* Eric Hodel (drbrain@segment7.net)
+
+=== License
+
+Copyright (c) 2007, 2008, Michael Granger. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+=== Attributions
+
+Darkfish uses the {Silk Icons}[http://www.famfamfam.com/lab/icons/silk/] set
+by Mark James.
+
+== jQuery license
+
+Copyright 2012 jQuery Foundation and other contributors
+
+http://jquery.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/pkg/emerald-0.0.1.alpha4/README.rdoc

@@ -0,0 +1,119 @@
+= Emerald -- Make your Ruby documentation a jewel, too
+
+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[http://rdoc.rubyforge.org], 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.
+
+== Installation
+
+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
+
+== Usage
+
+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
+
+== Features
+
+* Default theme has is centered around light blue/grey, just as Hanna was.
+* No frames.
+* Uses jQuery[http://jquery.com].
+* 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...
+
+== Weblinks
+
+* Sourcecode: https://github.com/Quintus/emerald
+* Bugtracker: https://github.com/Quintus/emerald/issues
+
+== Caveats
+
+* ToC generation only works for proper heading nestings, especially it
+  assumes your page to have <b>exactly one</b> 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 <tt>\A(?>[^ab]q)\s*%.*stuff(?<!badstuff)\w{2,4}(?:$|\\\\)</tt>.
+* 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
+
+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ć}[https://github.com/mislav] for creating the {Hanna RDoc
+template}[https://github.com/mislav/hanna], 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.
+
+== License
+
+Emerald is an RDoc HTML generator.
+
+Copyright © 2012 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 <http://www.gnu.org/licenses/>.
+
+=== Additional notes
+
+* 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.

data/pkg/emerald-0.0.1.alpha4/lib/rdoc/discover.rb

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

data/pkg/emerald-0.0.1.alpha4/lib/rdoc/generator/emerald.rb

@@ -0,0 +1,304 @@
+# -*- 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
+
+  # Minimal RDoc::Toplevel-alike object (i.e. it responds to the
+  # two methods required for rendering it, +full_name+ and
+  # +description+) that is used to create the index page if
+  # none was set. I really recommend to manually set a
+  # useful index page!
+  DummyStartPage = Struct.new(:full_name, :description) do
+    def initialize
+      super()
+      self.full_name = "Start page"
+      self.description =<<-DESC
+<h1>RDoc documentation</h1>
+<p>This is a dummy start page for the RDoc documentation of this project.</p>
+<p>You’re seeing it, because the original author didn’t specify a real start
+   page for this project’s documentation, so you may want to contact him and
+   make him aware of this.</p>
+<p>If you <em>are</em> the original author, try one or both of the following
+   code snippets to make your <strong>README.rdoc</strong> file the start
+   page of your documentation:</p>
+<pre>
+# In your gemspec:
+Gem::Specification.new do |spec|
+  # ...
+  # "-m" sets the start ("main") page. "-t" specifies
+  # the title to display in the window title bar.
+  spec.rdoc_options << "-m" << "README.rdoc" << "-t" "Docs for YourProject"
+end
+
+# In your Rakefile:
+RDoc::Task.new do |rt|
+  # ...
+  # Sets the start ("main") page and specifies the
+  # title to display in the window title bar:
+  rt.main = "README.rdoc"
+  rt.title = "Docs for YourProject"
+end
+</pre>
+<p>For the time being, use the navigation sidebar to the left
+   in order to read this documentation.</p>
+      DESC
+    end
+  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
+
+  # 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
+
+  # Outputs a string on standard output, but only if RDoc
+  # was invoked with the <tt>--debug</tt> switch.
+  def debug(str)
+    puts(str) if $DEBUG_RDOC
+  end
+
+  # Main hook method called by RDoc, triggers the generation process.
+  def generate(top_levels)
+    debug "Sorting classes, modules, and methods..."
+    @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
+      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
+
+  # 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
+    debug "Copying base 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|
+      debug "Processing toplevel #{toplevel.name}..."
+
+      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|
+        debug  "  => #{path}"
+        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
+        debug "  => This is the main page. Writing index.html."
+
+        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|
+      debug "Processing class/module #{classmod.full_name} (#{classmod.method_list.count} methods)..."
+
+      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|
+        debug "  => #{path}"
+        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"