emerald 0.0.1.alpha4 → 0.0.1

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

@@ -1,140 +0,0 @@
-= 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

@@ -1,119 +0,0 @@
-= 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

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

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

@@ -1,304 +0,0 @@
-# -*- 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"