etude_for_ruby 0.1.4 → 0.2.3

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/benchmarks/template_erb.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-require "benchmark"
-require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
-
-YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
-obj = YARD::Registry.at("YARD::CodeObjects::Base")
-
-TIMES = 3
-Benchmark.bm do |x|
-  x.report("trim-line") { TIMES.times { obj.format(:format => :html) } }
-  module YARD
-    module Templates
-      module Template
-        def erb(section, &block)
-          erb = ERB.new(cache(section), nil)
-          erb.filename = cache_filename(section).to_s
-          erb.result(binding, &block)
-        end
-      end
-    end
-  end
-  x.report("no-trim  ") { TIMES.times { obj.format(:format => :html) } }
-end

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/benchmarks/template_format.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-require "benchmark"
-require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
-
-YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
-obj = YARD::Registry.at("YARD::CodeObjects::Base")
-log.puts Benchmark.measure { obj.format(:format => :html) }

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/benchmarks/template_profile.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-require 'rubygems'
-require 'ruby-prof'
-# require 'benchmark'
-require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
-
-YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
-obj = YARD::Registry.at("YARD::CodeObjects::Base")
-
-# PerfTools::CpuProfiler.start("template_profile") do
-# end
-
-result = RubyProf.profile do
-  obj.format(:format => :html, :no_highlight => true)
-end
-
-printer = RubyProf::CallTreePrinter.new(result)
-printer.print(STDOUT)

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/benchmarks/yri_cache.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + "/../lib/yard"
-require "benchmark"
-include YARD::CLI
-
-class YARD::CLI::YRI
-  def print_object(object) end
-end
-
-def remove_cache
-  File.unlink(YRI::CACHE_FILE)
-end
-
-TIMES = 10
-NAME = 'YARD'
-remove_cache; YRI.run(NAME)
-Benchmark.bmbm do |x|
-  x.report("cache   ") { TIMES.times { YRI.run(NAME) } }
-  x.report("no-cache") { TIMES.times { remove_cache; YRI.run(NAME) } }
-end

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/bin/yard

@@ -1,13 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# We do all this work just to find the proper load path
-path = __FILE__
-while File.symlink?(path)
-  path = File.expand_path(File.readlink(path), File.dirname(path))
-end
-$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
-
-require 'yard'
-
-YARD::CLI::CommandParser.run(*ARGV)

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/bin/yardoc

@@ -1,13 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# We do all this work just to find the proper load path
-path = __FILE__
-while File.symlink?(path)
-  path = File.expand_path(File.readlink(path), File.dirname(path))
-end
-$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
-
-require 'yard'
-
-YARD::CLI::Yardoc.run(*ARGV)

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/bin/yri

@@ -1,13 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# We do all this work just to find the proper load path
-path = __FILE__
-while File.symlink?(path)
-  path = File.expand_path(File.readlink(path), File.dirname(path))
-end
-$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
-
-require 'yard'
-
-YARD::CLI::YRI.run(*ARGV)

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/docs/CodeObjects.md

@@ -1,115 +0,0 @@
-# @title CodeObjects Architecture
-
-# CodeObjects Architecture
-
-Code objects are Ruby objects that describe the code being documented. For instance,
-all classes, modules, methods, etc. are all extracted from the Ruby source as code
-objects. All of these code objects extend from the {YARD::CodeObjects::Base} class, which
-provides basic attributes like source location, source code, name and path.
-
-## CodeObjects Organization
-
-Code objects are divided into two basic types. {YARD::CodeObjects::NamespaceObject NamespaceObjects}
-and non-namespace objects. A namespace object refers to any object in Ruby that can have
-other objects defined inside of it. In the context of Ruby, this specifically means
-modules and classes (both of which are subclasses of `NamespaceObject`). These objects
-act like tree structures, maintaining a list of all of their direct children. All non
-namespace objects are simply subclasses of the Base class. The {YARD::CodeObjects::RootObject RootObject}
-is a special kind of `NamespaceObject` which refers to the top level namespace in Ruby.
-Methods that accept a namespace object as a parameter should also accept the symbol
-`:root` as a shortcut for the root object.
-
-The following is an overview of the classes within the `CodeObjects` namespace:
-
-![CodeObjects Class Diagram](images/code-objects-class-diagram.png)
-
-## Unique Path Representation
-
-All CodeObjects are uniquely defined by their implementation of {YARD::CodeObjects::Base#path}.
-This path is used to locate or store a code object in the {YARD::Registry}. It is therefore
-essential that any Base subclass return a unique String value for #path so that the
-object may co-exist with other objects in the Registry.
-
-In practice, a path is simply the conventional Ruby representation of a class,
-module, constant, class variable or method. For example, the following objects
-would have the following respective paths:
-
-* Class `Klass` inside module `Mod`: `Mod::Klass`
-* Instance method `bar` inside class `Foo`: `Foo#bar`
-* Class method `bar` inside class `Foo`: `Foo.bar`
-* Constant `VERSION` inside class `YARD`: `YARD::VERSION`
-* Class variable `@@abc` inside class `A`: `A::@@abc`
-
-## Registry
-
-CodeObjects classes are coupled with the {YARD::Registry} class which keeps track of
-all instantiated code objects. This is an explicit design choice to allow objects
-to be fetched, cached, imported and exported from a centralized location. As mentioned
-above, this coupling is a result of the fact that each object is uniquely identified by
-its path, which is used to implement lookups. You can read more about the registry
-in the {YARD::Registry} class.
-
-## Identity Map
-
-Code objects are instantiated using an identity-map like implementation that guarantees
-only one unique Ruby object exists for an object described by a specific path. This
-allows developers to create a code object without checking if it already exists in
-the {YARD::Registry}. The following example will only create one object:
-
-    id = ClassObject.new(:root, "MyClass").object_id #=> 13352
-    ClassObject.new(:root, "MyClass").object_id #=> 13352
-
-## Proxy Objects
-
-In addition to providing access to existing objects, a {YARD::CodeObjects::Proxy}
-class exists which can represent an object at a path that may or may not have been
-created. This is necessary to represent a reference to an object in code that is
-never defined in the same body of source code, or perhaps defined later. If any
-attributes of a proxy are accessed, it will immediately be resolved to the object
-at its declared path. In the case where such an object exists, it will act as
-a delegate to the object. However, if the object does not exist, a warning will
-be raised. Whenever arbitrary code objects are used, care should be taken in
-order to make sure attributes are not accessed on unresolvable proxies. An
-unresolvable proxy will return a class name of `Proxy` and #type of `:proxy`,
-for example:
-
-    P(:InvalidObject).type == :proxy  #=> true
-    P(:InvalidObject).is_a?(Proxy)    #=> true
-
-## Adding Data to Code Objects
-
-Code objects act as hash-like structures that allow any arbitrary value to be set.
-This allows easy extending of existing objects without creating custom subclasses.
-For instance, to add a timestamp to a method object (when it was modified, maybe),
-it is possible to simply do:
-
-    object = MethodObject.new(:root, "my_method")
-    object[:modified_at] = Time.now
-
-This value can now be retrieved on this object both by the hash `[]` syntax as
-well as like any other method:
-
-    object.modified_at #=> 2009-06-03 20:08:46 -0400
-
-## Creating a Custom CodeObject
-
-It should first be mentioned that creating a custom code object should not be
-necessary in most cases, except when functionality that cannot be represented
-by classical Ruby objects is added. A good example *might* be a test class,
-which although is technically a Ruby class, has a significantly different purpose
-in documentation and needs a different set of metadata, as well as its own
-representation in documentation.
-
-The {YARD::CodeObjects::Base#path} implementation is the most important part of the
-code object architecture. The first thing any custom code object must guarantee is
-that its path value is unique among all other objects. The recommended way to do this
-with custom objects is to add a descriptive prefix to the path. For example, the
-following is an implementation of the path for a hypothetical `FooObject`:
-
-    def path
-      "__FooPrefix" + sep + super
-    end
-
-Note that if our FooObject is a `NamespaceObject`, meaning if it can have child
-FooObjects defined inside of it, you may need to verify that the prefix is only
-applied once.

data/vendor/bundle/ruby/2.2.0/gems/yard-0.9.8/docs/GettingStarted.md

@@ -1,674 +0,0 @@
-# @title Getting Started Guide
-
-# Getting Started with YARD
-
-There are a few ways which YARD can be of use to you or your project. This
-document will cover the most common ways to use YARD:
-
-* [Documenting Code with YARD](#docing)
-* [Using YARD to Generate Documentation](#using)
-* [Configuring YARD](#config)
-* [Extending YARD](#extending)
-* [Templating YARD](#templating)
-* [Plugin Support](#plugins)
-
-<a name="docing"></a>
-
-## Documenting Code with YARD
-
-By default, YARD is compatible with the same RDoc syntax most Ruby developers
-are already familiar with. However, one of the biggest advantages of YARD is
-the extended meta-data syntax, commonly known as "tags", that you can use
-to express small bits of information in a structured and formal manner. While
-RDoc syntax expects you to describe your method in a completely free-form
-manner, YARD recommends declaring your parameters, return types, etc. with
-the `@tag` syntax, which makes outputting the documentation more consistent
-and easier to read. Consider the RDoc documentation for a method to_format:
-
-    # Converts the object into textual markup given a specific `format`
-    # (defaults to `:html`)
-    #
-    # == Parameters:
-    # format::
-    #   A Symbol declaring the format to convert the object to. This
-    #   can be `:text` or `:html`.
-    #
-    # == Returns:
-    # A string representing the object in a specified
-    # format.
-    #
-    def to_format(format = :html)
-      # format the object
-    end
-
-While this may seem easy enough to read and understand, it's hard for a machine
-to properly pull this data back out of our documentation. Also we've tied our
-markup to our content, and now our documentation becomes hard to maintain if
-we decide later to change our markup style (maybe we don't want the ":" suffix
-on our headers anymore).
-
-In YARD, we would simply define our method as:
-
-    # Converts the object into textual markup given a specific format.
-    #
-    # @param format [Symbol] the format type, `:text` or `:html`
-    # @return [String] the object converted into the expected format.
-    def to_format(format = :html)
-      # format the object
-    end
-
-Using tags we can add semantic metadata to our code without worrying about
-presentation. YARD will handle presentation for us when we decide to generate
-documentation later.
-
-## Which Markup Format?
-
-YARD does not impose a specific markup. The above example uses standard RDoc
-markup formatting, but YARD also supports textile and markdown via the
-command-line switch or `.yardopts` file (see below). This means that you are
-free to use whatever formatting you like. This guide is actually written
-using markdown. YARD, however, does add a few important syntaxes that are
-processed no matter which markup formatting you use, such as tag support
-and inter-document linking. These syntaxes are discussed below.
-
-## Adding Tags to Documentation
-
-The tag syntax that YARD uses is the same @tag-style syntax you may have seen
-if you've ever coded in Java, Python, PHP, Objective-C or a myriad of other
-languages. The following tag adds an author tag to your class:
-
-    # @author Loren Segal
-    class MyClass
-    end
-
-To allow for large amounts of text, the @tag syntax will recognize any indented
-lines following a tag as part of the tag data. For example:
-
-    # @deprecated Use {#my_new_method} instead of this method because
-    #   it uses a library that is no longer supported in Ruby 1.9.
-    #   The new method accepts the same parameters.
-    def mymethod
-    end
-
-### List of Tags
-
-A list of tags can be found in {file:docs/Tags.md#taglist}
-
-### Reference Tags
-
-To reduce the amount of duplication in writing documentation for repetitive
-code, YARD introduces "reference tags", which are not quite tags, but not
-quite docstrings either. In a sense, they are tag (and docstring) modifiers.
-Basically, any docstring (or tag) that begins with "(see OTHEROBJECT)" will
-implicitly link the docstring or tag to the "OTHEROBJECT", copying any data
-from that docstring/tag into your current object. Consider the example:
-
-    class MyWebServer
-      # Handles a request
-      # @param request [Request] the request object
-      # @return [String] the resulting webpage
-      def get(request) "hello" end
-
-      # (see #get)
-      def post(request) "hello" end
-    end
-
-The above `#post` method takes the docstring and all tags (`param` and `return`)
-of the `#get` method. When you generate HTML documentation, you will see this
-duplication automatically, so you don't have to manually type it out. We can
-also add our own custom docstring information below the "see" reference, and
-whatever we write will be appended to the docstring:
-
-    # (see #get)
-    # @note This method may modify our application state!
-    def post(request) self.state += 1; "hello" end
-
-Here we added another tag, but we could have also added plain text. The
-text must be appended *after* the `(see ...)` statement, preferably on
-a separate line.
-
-Note that we don't have to "refer" the whole docstring. We can also link
-individual tags instead. Since "get" and "post" actually have different
-descriptions, a more accurate example would be to only refer our parameter
-and return tags:
-
-    class MyWebServer
-      # Handles a GET request
-      # @param request [Request] the request object
-      # @return [String] the resulting webpage
-      def get(request) "hello" end
-
-      # Handles a POST request
-      # @note This method may modify our application state!
-      # @param (see #get)
-      # @return (see #get)
-      def post(request) self.state += 1; "hello" end
-    end
-
-The above copies all of the param and return tags from `#get`. Note that you
-cannot copy individual tags of a specific type with this syntax.
-
-## Declaring Types
-
-Some tags also have an optional "types" field which let us declare a list of
-types associated with the tag. For instance, a return tag can be declared
-with or without a types field.
-
-    # @return [String, nil] the contents of our object or nil
-    #   if the object has not been filled with data.
-    def validate; end
-
-    # We don't care about the "type" here:
-    # @return the object
-    def to_obj; end
-
-The list of types is in the form `[type1, type2, ...]` and is mostly free-form,
-so we can also specify duck-types or constant values. For example:
-
-    # @param argname [#to_s] any object that responds to `#to_s`
-    # @param argname [true, false] only true or false
-
-Note the latter example can be replaced by the meta-type "Boolean".
-Another meta-type is "void", which stands for "no meaningful value"
-and is used for return values. These meta-types are by convention
-only, but are recommended.
-
-List types can be specified in the form `CollectionClass<ElementType, ...>`.
-For instance, consider the following Array that holds a set of Strings and
-Symbols:
-
-    # @param list [Array<String, Symbol>] the list of strings and symbols.
-
-We mentioned that these type fields are "mostly" free-form. In truth, they
-are defined "by convention". To view samples of common type specifications
-and recommended conventions for writing type specifications, see
-[http://yardoc.org/types.html](http://yardoc.org/types.html). Note that these
-conventions may change every now and then, although we are working on a more
-"formal" type specification proposal.
-
-## Documenting Attributes
-
-To document a Ruby attribute, add documentation text above the attribute
-definition.
-
-    # Controls the amplitude of the waveform.
-    # @return [Numeric] the amplitude of the waveform
-    attr_accessor :amplitude
-
-As a short-hand syntax for declaring reader and writer attribute pairs,
-YARD will automatically wire up the correct method types and information
-by simply defining documentation in the `@return` tag. For example,
-the following declaration will show the correct information for the
-`waveform` attribute, both for the getter's return type and the
-setter's value parameter type: 
-
-    # @return [Numeric] the amplitude of the waveform
-    attr_accessor :amplitude
-
-In this case, the most important details for the attribute are the
-object type declaration and its descriptive text.
-
-### Documentation for a Separate Attribute Writer
-
-Usually an attribute will get and set a value using the same syntax,
-so there is no reason to have separate documentation for an attribute
-writer. In the above `amplitude` case, the `Numeric` type is both used
-for the getter and setter types.
-
-Sometimes, however, you might want to have separate documentation
-for the getter and setter. In this case, you would still add
-the documentation text to the getter declaration (or `attr_accessor`)
-and use `@overload` tags to declare the separate docstrings. For example:
-
-    # @overload amplitude
-    #   Gets the current waveform amplitude.
-    #   @return [Numeric] the amplitude of the waveform
-    # @overload amplitude=(value)
-    #   Sets the new amplitude.
-    #   @param value [Numeric] the new amplitude value
-    #   @note The new amplitude will only take effect if {#restart}
-    #     is called on the stream.
-
-Note that by default, YARD exposes the reader portion of the attribute
-in HTML output. If you have separate `attr_reader` and `attr_writer`
-declarations, make sure to put your documentation (for both reader
-and writer methods) on the reader declaration using `@overload`
-tags as described above. For example:
-
-    # @overload ...documentation here...
-    attr_reader :amplitude
-
-    # This documentation will be ignored by YARD.
-    attr_writer :amplitude
-
-## Documenting Custom DSL Methods
-
-Application code in Ruby often makes use of DSL style metaprogrammed methods.
-The most common is the `attr_accessor` method, which of course has built-in
-support in YARD. However, frameworks and libraries often expose custom
-methods that perform similar metaprogramming tasks, and it is often useful
-to document their functionality in your application. Consider the `property`
-method in a project like [DataMapper](http://datamapper.org), which creates
-a typed attribute for a database model. The code might look like:
-
-    class Post
-      include DataMapper::Resource
-
-      property :title, String
-    end
-
-As of version 0.7.0, YARD will automatically pick up on these basic methods if
-you document them with a docstring. Therefore, simply adding some comments to
-the code will cause it to generate documentation:
-
-    class Post
-      include DataMapper::Resource
-
-      # @return [String] the title property of the post
-      property :title, String
-    end
-
-Note that YARD uses the first argument in the method call to determine the
-method name. In some cases, this would not be the method name, and you would
-need to declare it manually. You can do so with the `@!method` directive:
-
-    # @!method foo
-    create_a_foo_method
-
-The @!method directive can also accept a full method signature with parameters:
-
-    # @!method foo(name, opts = {})
-    create_a_foo_method
-
-You can also set visibility and scope, or modify the method signature with
-extra tags. The following adds documentation for a private class method:
-
-    # @!method foo(opts = {})
-    # The foo method!
-    # @!scope class
-    # @!visibility private
-    create_a_private_foo_class_method
-
-Finally, you can tag a method as an attribute by replacing the @!method
-tag with @!attribute. The @!attribute directive allows for the flags [r], [w],
-or [rw] to declare a readonly, writeonly, or readwrite attribute, respectively.
-
-    # @!attribute [w]
-    # The writeonly foo attribute!
-    a_writeonly_attribute :foo
-
-(Note that if the name can be automatically detected, you do not need to
-specify it in the @!method or @!attribute directives)
-
-However, you will notice a few drawbacks with this basic support:
-
-1. There is a fair bit of duplication in such documentation. Specifically, we
-   repeat the term String and title twice in the property example.
-2. We must write a code comment for this property to show up in the documentation.
-   If we do not write a comment, it is ignored.
-
-### Macros
-
-Fortunately YARD 0.7.0 also adds macros, a powerful way to add support for
-these DSL methods on the fly without writing extra plugins. Macros allow
-you to interpolate arguments from the method call inside the docstring,
-reducing duplication. If we re-wrote the `property` example from above
-using a macro, it might look like:
-
-    class Post
-      include DataMapper::Resource
-
-      # @!macro dm.property
-      # @return [$2] the $1 $0 of the post
-      property :title, String
-    end
-
-(Note that $0 represents the method call, in this case `property`. The rest
-are arguments in the method call.)
-
-The above example is equivalent to the first version shown in the previous
-section. There is also some extra benefit to using this macro, in that we
-can re-apply it to any other property in our class by simply calling on
-the macro. The following:
-
-    # @!macro dm.property
-    property :view_count, Integer
-
-Would be equivalent to:
-
-    # @return [Integer] the view_count property of the post
-    property :view_count, Integer
-
-Finally, macros can be "attached" to method calls, allowing them to be implicitly
-activated every time the method call is seen in the source code of the class,
-or an inheriting class. By simply adding the `[attach]` flag, the macro
-becomes implicit on future calls. All of the properties below get documented
-by using this snippet:
-
-    class Post
-      include DataMapper::Resource
-
-      # @!macro [attach] dm.property
-      # @return [$2] the $1 $0 of the post
-      property :title, String
-      property :view_count, Integer
-      property :email, String
-    end
-
-You can read more about macros in the {file:docs/Tags.md Tags Overview} document.
-
-## Customized YARD Markup
-
-YARD supports a special syntax to link to other code objects, URLs, files,
-or embed docstrings between documents. This syntax has the general form
-of `{Name OptionalTitle}` (where `OptionalTitle` can have spaces, but `Name`
-cannot).
-
-### Linking Objects `{...}`
-
-To link another "object" (class, method, module, etc.), use the format:
-
-    {ObjectName#method OPTIONAL_TITLE}
-    {Class::CONSTANT My constant's title}
-    {#method_inside_current_namespace}
-
-Without an explicit title, YARD will use the relative path to the object as
-the link name. Note that you can also use relative paths inside the object
-path to refer to an object inside the same namespace as your current docstring.
-
-Note that the `@see` tag automatically links its data. You should not use
-the link syntax in this tag:
-
-    # @see #methodname   <- Correct.
-    # @see {#methodname} <- Incorrect.
-
-If you want to use a Hash, prefix the first { with "!":
-
-   # !{ :some_key => 'value' }
-
-### Linking URLs `{http://...}`
-
-URLs are also linked using this `{...}` syntax:
-
-    {http://example.com Optional Title}
-    {mailto:email@example.com}
-
-### Linking Files `{file:...}`
-
-Files can also be linked using this same syntax but by adding the `file:`
-prefix to the object name. Files refer to extra readme files you added
-via the command-line. Consider the following examples:
-
-    {file:docs/GettingStarted.md Getting Started}
-    {file:mypage.html Name#anchor}
-
-As shown, you can also add an optional `#anchor` if the page is an HTML link.
-
-### Embedding Docstrings `{include:...}`
-
-We saw the `(see ...)` syntax above, which allowed us to link an entire docstring
-with another. Sometimes, however, we just want to copy docstring text without
-tags. Using the same `{...}` syntax, but using the `include:` prefix, we can
-embed a docstring (minus tags) at a specific point in the text.
-
-    # This class is cool
-    # @abstract
-    class Foo; end
-
-    # This is another class. {include:Foo} too!
-    class Bar; end
-
-The docstring for Bar becomes:
-
-    "This is another class. This class is cool too!"
-
-### Embedding Files `{include:file:...}`
-
-You can embed the contents of files using `{include:file:path/to/file}`,
-similar to the `{include:OBJECT}` tag above. If the file uses a specific markup
-type, it will be applied and embedded as marked up text. The following
-shows how the tag can be used inside of comments:
-
-    # Here is an example of a highlighted Ruby file:
-    #
-    # {include:file:examples/test.rb}
-
-### Rendering Objects `{render:...}`
-
-Entire objects can also be rendered in place in documentation. This can be
-used for guide-style documentation which does not document the entire source
-tree, but instead selectively renders important classes or methods. Consider
-the following documentation inside of a README file:
-
-    !!!plain
-    = igLatinPay!
-
-    This library adds pig latin methods to the string class, allowing you
-    to transform sentences into pig latin.
-
-    {render:String#pig_latin}
-
-    You can also un-pig-latin-ify a word or sentence:
-
-    {render:String#de_pig_latin}
-
-The above would render the methods in place inside the README document,
-allowing you to summarize a small library in a single file.
-
-<a name="using"></a>
-
-## Using YARD to Generate Documentation
-
-### `yard` Executable
-
-YARD ships with a single executable aptly named `yard`. In addition to
-generating standard documentation for your project, you would use this tool
-if you wanted to:
-
-* Document all installed gems
-* Run a local documentation server
-* Generate UML diagrams using [Graphviz][graphviz]
-* View `ri`-style documentation
-* Diff your documentation
-* Analyze documentation statistics.
-
-The following commands are available in YARD 0.6.x (see `yard help` for a
-full list):
-
-    Usage: yard <command> [options]
-
-    Commands:
-    config   Views or edits current global configuration
-    diff     Returns the object diff of two gems or .yardoc files
-    doc      Generates documentation
-    gems     Builds YARD index for gems
-    graph    Graphs class diagram using Graphviz
-    help     Retrieves help for a command
-    ri       A tool to view documentation in the console like `ri`
-    server   Runs a local documentation server
-    stats    Prints documentation statistics on a set of files
-
-Note that `yardoc` is an alias for `yard doc`, and `yri` is an alias for
-`yard ri`. These commands are maintained for backwards compatibility.
-
-### `.yardopts` Options File
-
-Unless your documentation is very small, you'll end up needing to run `yardoc`
-with many options.  The `yardoc` tool will use the options found in this file.
-It is recommended to check this in to your repository and distribute it with
-your source. This file is placed at the root of your project (in the directory
-you run `yardoc` from) and contains all of arguments you would otherwise pass
-to the command-line tool. For instance, if you often type:
-
-    yardoc --no-private --protected app/**/*.rb - README LEGAL COPYING
-
-You can place the following into your `.yardopts`:
-
-    --no-private --protected app/**/*.rb - README LEGAL COPYING
-
-This way, you only need to type:
-
-    yardoc
-
-Any extra switches passed to the command-line now will be appended to your
-`.yardopts` options.
-
-Note that options for `yardoc` are discussed in the {file:README.md README},
-and a full overview of the `.yardopts` file can be found in {YARD::CLI::Yardoc}.
-
-### Documenting Extra Files
-
-"Extra files" are extra guide style documents that help to give a brief overview
-of how to use your library/framework, as well as any extra information that
-might be vital for your users. The most common "extra file" is the README,
-which is automatically detected by YARD if found in the root of your project
-(any file starting with `README*`). You can specify extra files on the command
-line (or in the `.yardopts` file) by listing them after the '-' separator:
-
-    yardoc lib/**/*.rb ext/**/*.c - LICENSE.txt
-
-Note that the README will automatically be picked up, so you do not need to
-specify it. If you don't want to modify the default file globs, you can ignore
-the first set of arguments:
-
-    yardoc - LICENSE.txt
-
-Below you can read about how to customize the look of these extra files, both
-with markup and pretty titles.
-
-#### Adding Meta-Data to Extra Files
-
-You can add YARD-style `@tag` metadata to the top of any extra file if prefixed
-by a `#` hash comment. YARD allows for arbitrary meta-data, but pays special
-attention to the tags `@markup`, `@encoding`, and `@title`. Note that there
-cannot be any whitespace before the tags. Here is an example of some tag data
-in a README:
-
-    # @markup markdown
-    # @title The Best Library in the World!
-    # @author The Author Name
-
-    This is the best library you will ever meet. Lipsum ...
-
-The `@markup` tag allows you to specify a markup format to use for the file,
-including "markdown", "textile", "rdoc", "ruby", "text", "html", or "none"
-(no markup). This can be used when the markup cannot be auto-detected using
-the extension of the filename, if the file has no extension, or if you want
-to override the auto-detection.
-
-By using `@encoding` you can specify a non-standard encoding. Note that
-`yardoc --charset` sets the global encoding (for all comments / files),
-so if you are using unicode across all your files, you can specify it there.
-Using the `@encoding` tag might be used to override the default global
-charset, say, if you had a localized `README.jp` file with SJIS data.
-Also note that this only affects Ruby 1.9.x, as Ruby 1.8 is not properly
-encoding aware.
-
-The `@title` tag allows you to specify a full title name for the document.
-By default, YARD uses the filename as the title of the document and lists
-it in the file list in the index and file menu. In some cases, the file name
-might not be descriptive enough, so YARD allows you to specify a full title:
-
-    contents of TITLE.txt:
-    # @title The Title of The Document
-
-Currently all other meta-data is hidden from view, though accessible
-programmatically using the {YARD::CodeObjects::ExtraFileObject} class.
-
-You can wrap the meta data section in an HTML comment to prevent it
-from being displayed in rendered markdown on GitHub:
-
-    <!--
-    # @markup markdown
-    # @title The Best Library in the World!
-    # @author The Author Name
-    -->
-
-    This is the best library you will ever meet. Lipsum ...
-
-<a name="config"></a>
-
-## Configuring YARD
-
-YARD (0.6.2+) supports a global configuration file stored in `~/.yard/config`.
-This file is stored as a YAML file and can contain arbitrary keys and values
-that can be used by YARD at run-time. YARD defines specific keys that are used
-to control various features, and they are listed in {YARD::Config::DEFAULT_CONFIG_OPTIONS}.
-A sample configuration file might look like:
-
-    :load_plugins: false
-    :ignored_plugins:
-      - my_plugin
-      - my_other_plugin
-    :autoload_plugins:
-      - my_autoload_plugin
-    :safe_mode: false
-
-You can also view and edit these configuration options from the commandline
-using the `yard config` command. To list your configuration, use `yard config --list`.
-To view a key, use `yard config ITEM`, and to set it, use `yard config ITEM VALUE`.
-
-<a name="extending"></a>
-
-## Extending YARD
-
-There are many ways to extend YARD to support non-standard Ruby syntax (DSLs),
-add new meta-data tags or programmatically access the intermediate metadata
-and documentation from code. An overview of YARD's full architecture can be
-found in the {file:docs/Overview.md} document.
-
-For information on adding support for Ruby DSLs, see the {file:docs/Handlers.md}
-and {file:docs/Parser.md} architecture documents.
-
-For information on adding extra tags, see {file:docs/Tags.md}.
-
-For information on accessing the data YARD stores about your documentation,
-look at the {file:docs/CodeObjects.md} architecture document.
-
-<a name="templating"></a>
-
-## Templating YARD
-
-In many cases you may want to change the style of YARD's templates or add extra
-information after extending it. The {file:docs/Templates.md} architecture
-document covers the basics of how YARD's templating system works.
-
-<a name="plugins"></a>
-
-## Plugin Support
-
-YARD will allow any RubyGem installed on your system (or in your Gemfile)
-to be loaded as a plugin provided it has a name with the prefix of
-`yard-` or `yard_`. In order to load a plugin, use the `--plugin`
-switch with the short-name (name minus the `yard-` prefix) or full-name
-of the gem:
-
-    $ gem install yard-custom-plugin
-    ...
-    $ yard doc --plugin custom-plugin
-    or
-    $ yard doc --plugin yard-custom-plugin
-
-Note: you can also put this switch in your `.yardopts` file. See the
-      `.yardopts` section above for more information.
-
-You can use this functionality to load a custom plugin that
-[extend](#extending) YARD's functionality. A good example of this
-is the [yard-rspec][yard-rspec] plugin, which adds [RSpec][rspec] specifications
-to your documentation (`yardoc` and `yri`). You can try it out by installing
-the gem or cloning the project and trying the example:
-
-    $ gem install yard-rspec
-
- You can then load the plugin with:
-
-    $ yard doc --plugin rspec
-
-YARD also provides a way to temporarily disable plugins on a per-user basis.
-To disable a plugin create the file `~/.yard/ignored_plugins` with a list
-of plugin names separated by newlines. Note that the `.yard` directory might
-not exist, so you may need to create it.
-
-[graphviz]:http://www.graphviz.org
-[yard-rspec]:http://github.com/lsegal/yard-spec-plugin
-[rspec]:http://rspec.info