Added super-hacky script to generate the wiki reference pages.

tasks/wiki.rake

@@ -1,11 +1,21 @@
+$LOAD_PATH.unshift(
+  File.expand_path(File.join(File.dirname(__FILE__), '../yard/lib'))
+)
+$LOAD_PATH.unshift(File.expand_path('.'))
+$LOAD_PATH.uniq!
+
 require 'google/api_client'
+require 'rake'
+require 'rake/clean'
+
+CLOBBER.include('wiki')
 
 CACHE_PREFIX =
   "http://www.gmodules.com/gadgets/proxy/container=default&debug=0&nocache=0/"
 
 namespace :wiki do
   desc 'Autogenerate wiki pages'
-  task :generate do
+  task :supported_apis do
     output = <<-WIKI
 #summary The list of supported APIs
 
@@ -23,12 +33,15 @@ WIKI
       end
     end
     for api_name, api in preferred_apis
-      output += (
+      if api.documentation.to_s != "" && api.title != ""
-        "||#{CACHE_PREFIX}#{api['icons']['x16']}||" +
+        output += (
-        "[#{api.documentation} #{api.title}]||" +
+          "||#{CACHE_PREFIX}#{api['icons']['x16']}||" +
-        "#{api.description}||\n"
+          "[#{api.documentation} #{api.title}]||" +
-      )
+          "#{api.description}||\n"
+        )
+      end
     end
+    output.gsub!(/-32\./, "-16.")
     wiki_path = File.expand_path(
       File.join(File.dirname(__FILE__), '../wiki/'))
     Dir.mkdir(wiki_path) if !File.exist?(wiki_path)
@@ -36,6 +49,33 @@ WIKI
       file.write(output)
     end
   end
+
+  task 'generate' => ['wiki:supported_apis']
 end
 
-# task 'clobber' => ['wiki:clobber_wiki']
+begin
+  require 'yard'
+  require 'yard/rake/wikidoc_task'
+
+  namespace :wiki do
+    desc 'Generate Wiki Documentation with YARD'
+    YARD::Rake::WikidocTask.new do |yardoc|
+      yardoc.name = 'reference'
+      yardoc.options = [
+        '--verbose',
+        '-e', 'yard/lib/yard-google-code.rb',
+        '-p', 'yard/templates',
+        '-f', 'wiki',
+        '-o', 'wiki'
+      ]
+      yardoc.files = [
+        'lib/**/*.rb', 'ext/**/*.c', '-', 'README.md', 'CHANGELOG.md'
+      ]
+    end
+
+    task 'generate' => ['wiki:reference', 'wiki:supported_apis']
+  end
+rescue LoadError
+  # If yard isn't available, it's not the end of the world
+  warn('YARD unavailable. Cannot fully generate wiki.')
+end

yard/bin/yard-wiki

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(
+  File.expand_path(File.join(File.dirname(__FILE__), '../lib'))
+)
+$LOAD_PATH.uniq!
+
+require 'yard/cli/wiki'
+
+YARD::CLI::Wiki.run(*ARGV)

yard/lib/yard-google-code.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
+$LOAD_PATH.uniq!
+
+YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/../templates'
+require 'yard/templates/template'
+require 'yard/templates/helpers/wiki_helper'
+
+::YARD::Templates::Template.extra_includes |= [
+  YARD::Templates::Helpers::WikiHelper
+]
+
+require 'yard/serializers/wiki_serializer'

yard/lib/yard/cli/wiki.rb

@@ -0,0 +1,44 @@
+require 'yard'
+require 'yard/serializers/wiki_serializer'
+require 'yard/cli/yardoc'
+
+module YARD
+  module CLI
+    class Wiki < Yardoc
+      # Creates a new instance of the commandline utility
+      def initialize
+        super
+        @options = SymbolHash.new(false)
+        @options.update(
+          :format => :html,
+          :template => :default,
+          :markup => :rdoc, # default is :rdoc but falls back on :none
+          :serializer => YARD::Serializers::WikiSerializer.new, # Sigh. :-(
+          :default_return => "Object",
+          :hide_void_return => false,
+          :no_highlight => false,
+          :files => [],
+          :verifier => Verifier.new
+        )
+        @visibilities = [:public]
+        @assets = {}
+        @excluded = []
+        @files = []
+        @hidden_tags = []
+        @use_cache = false
+        @use_yardopts_file = true
+        @use_document_file = true
+        @generate = true
+        @options_file = DEFAULT_YARDOPTS_FILE
+        @statistics = true
+        @list = false
+        @save_yardoc = true
+        @has_markup = false
+
+        if defined?(::Encoding) && ::Encoding.respond_to?(:default_external=)
+          ::Encoding.default_external, ::Encoding.default_internal = 'utf-8', 'utf-8'
+        end
+      end
+    end
+  end
+end

yard/lib/yard/rake/wikidoc_task.rb

@@ -0,0 +1,27 @@
+require 'rake'
+require 'rake/tasklib'
+require 'yard/rake/yardoc_task'
+require 'yard/cli/wiki'
+
+module YARD
+  module Rake
+    # The rake task to run {CLI::Yardoc} and generate documentation.
+    class WikidocTask < YardocTask
+      protected
+
+      # Defines the rake task
+      # @return [void]
+      def define
+        desc "Generate Wiki Documentation with YARD"
+        task(name) do
+          before.call if before.is_a?(Proc)
+          yardoc = YARD::CLI::Wiki.new
+          yardoc.parse_arguments *(options + files)
+          yardoc.options[:verifier] = verifier if verifier
+          yardoc.run
+          after.call if after.is_a?(Proc)
+        end
+      end
+    end
+  end
+end

yard/lib/yard/serializers/wiki_serializer.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+
+require 'yard/serializers/file_system_serializer'
+
+module YARD
+  module Serializers
+    ##
+    # Subclass required to get correct filename for the top level namespace.
+    # :-(
+    class WikiSerializer < FileSystemSerializer
+      # Post-process the data before serializing.
+      # Strip unnecessary whitespace.
+      # Convert stuff into more wiki-friendly stuff.
+      # FULL OF HACKS!
+      def serialize(object, data)
+        data = data.encode("UTF-8")
+        if object == "Sidebar.wiki"
+          data = data.gsub(/^#sidebar Sidebar\n/, "")
+        end
+        data = data.gsub(/\n\s*\n/, "\n")
+        # ASCII/UTF-8 erb error work-around.
+        data = data.gsub(/--/, "—")
+        data = data.gsub(/——/, "----")
+        data = data.gsub(/----\n----/, "----")
+        # HACK! Google Code Wiki treats <code> blocks like <pre> blocks.
+        data = data.gsub(/\<code\>(.+)\<\/code\>/, "`\\1`")
+        super(object, data)
+      end
+
+      def serialized_path(object)
+        return object if object.is_a?(String)
+
+        if object.is_a?(CodeObjects::ExtraFileObject)
+          fspath = ['file.' + object.name + (extension.empty? ? '' : ".#{extension}")]
+        else
+          # This line is the only change of significance.
+          # Changed from 'top-level-namespace' to 'TopLevelNamespace' to
+          # conform to wiki word page naming convention.
+          objname = object != YARD::Registry.root ? object.name.to_s : "TopLevelNamespace"
+          objname += '_' + object.scope.to_s[0,1] if object.is_a?(CodeObjects::MethodObject)
+          fspath = [objname + (extension.empty? ? '' : ".#{extension}")]
+          if object.namespace && object.namespace.path != ""
+            fspath.unshift(*object.namespace.path.split(CodeObjects::NSEP))
+          end
+        end
+
+        # Don't change the filenames, it just makes it more complicated
+        # to figure out the original name.
+        #fspath.map! do |p|
+        #  p.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        #end
+
+        # Remove special chars from filenames.
+        # Windows disallows \ / : * ? " < > | but we will just remove any
+        # non alphanumeric (plus period, underscore and dash).
+        fspath.map! do |p|
+          p.gsub(/[^\w\.-]/) do |x|
+            encoded = '_'
+
+            x.each_byte { |b| encoded << ("%X" % b) }
+            encoded
+          end
+        end
+        fspath.join("")
+      end
+    end
+  end
+end

yard/lib/yard/templates/helpers/wiki_helper.rb

@@ -0,0 +1,502 @@
+require 'cgi'
+require 'rdiscount'
+
+module YARD
+  module Templates::Helpers
+    # The helper module for HTML templates.
+    module WikiHelper
+      include MarkupHelper
+
+      # @return [String] escapes text
+      def h(text)
+        out = ""
+        text = text.split(/\n/)
+        text.each_with_index do |line, i|
+          out <<
+          case line
+          when /^\s*$/; "\n\n"
+          when /^\s+\S/, /^=/; line + "\n"
+          else; line + (text[i + 1] =~ /^\s+\S/ ? "\n" : " ")
+          end
+        end
+        out.strip
+      end
+
+      # @return [String] wraps text at +col+ columns.
+      def wrap(text, col = 72)
+        text.strip.gsub(/(.{1,#{col}})( +|$\n?)|(.{1,#{col}})/, "\\1\\3\n")
+      end
+
+      # Escapes a URL
+      # 
+      # @param [String] text the URL
+      # @return [String] the escaped URL
+      def urlencode(text)
+        CGI.escape(text.to_s)
+      end
+
+      def indent(text, len = 2)
+        text.gsub(/^/, ' ' * len)
+      end
+
+      def unindent(text)
+        lines = text.split("\n", -1)
+        min_indent_size = text.size
+        for line in lines
+          indent_size = (line.gsub("\t", "  ") =~ /[^\s]/) || text.size
+          min_indent_size = indent_size if indent_size < min_indent_size
+        end
+        text.gsub("\t", "  ").gsub(Regexp.new("^" + " " * min_indent_size), '')
+      end
+
+      # @group Converting Markup to HTML
+
+      # Turns text into HTML using +markup+ style formatting.
+      #
+      # @param [String] text the text to format
+      # @param [Symbol] markup examples are +:markdown+, +:textile+, +:rdoc+.
+      #   To add a custom markup type, see {MarkupHelper}
+      # @return [String] the HTML
+      def htmlify(text, markup = options[:markup])
+        markup_meth = "html_markup_#{markup}"
+        return text unless respond_to?(markup_meth)
+        return "" unless text
+        return text unless markup
+        load_markup_provider(markup)
+        html = send(markup_meth, text)
+        if html.respond_to?(:encode)
+          html = html.force_encoding(text.encoding) # for libs that mess with encoding
+          html = html.encode(:invalid => :replace, :replace => '?')
+        end
+        html = resolve_links(html)
+        html = html.gsub(/<pre>(?:\s*<code>)?(.+?)(?:<\/code>\s*)?<\/pre>/m) do
+          str = unindent($1).strip
+          str = html_syntax_highlight(CGI.unescapeHTML(str)) unless options[:no_highlight]
+          str
+        end unless markup == :text
+        html
+      end
+
+      # Converts Markdown to HTML
+      # @param [String] text input Markdown text
+      # @return [String] output HTML
+      # @since 0.6.0
+      def html_markup_markdown(text)
+        Markdown.new(text).to_html
+      end
+
+      # Converts Textile to HTML
+      # @param [String] text the input Textile text
+      # @return [String] output HTML
+      # @since 0.6.0
+      def html_markup_textile(text)
+        doc = markup_class(:textile).new(text)
+        doc.hard_breaks = false if doc.respond_to?(:hard_breaks=)
+        doc.to_html
+      end
+
+      # Converts plaintext to HTML
+      # @param [String] text the input text
+      # @return [String] the output HTML
+      # @since 0.6.0
+      def html_markup_text(text)
+        "<pre>" + text + "</pre>"
+      end
+
+      # Converts HTML to HTML
+      # @param [String] text input html
+      # @return [String] output HTML
+      # @since 0.6.0
+      def html_markup_html(text)
+        text
+      end
+
+      # @return [String] HTMLified text as a single line (paragraphs removed)
+      def htmlify_line(*args)
+        htmlify(*args)
+      end
+
+      # Fixes RDoc behaviour with ++ only supporting alphanumeric text.
+      #
+      # @todo Refactor into own SimpleMarkup subclass
+      def fix_typewriter(text)
+        text.gsub(/\+(?! )([^\n\+]{1,900})(?! )\+/) do
+          type_text, pre_text, no_match = $1, $`, $&
+          pre_match = pre_text.scan(%r(</?(?:pre|tt|code).*?>))
+          if pre_match.last.nil? || pre_match.last.include?('/')
+            '`' + h(type_text) + '`'
+          else
+            no_match
+          end
+        end
+      end
+
+      # Don't allow -- to turn into &#8212; element. The chances of this being
+      # some --option is far more likely than the typographical meaning.
+      #
+      # @todo Refactor into own SimpleMarkup subclass
+      def fix_dash_dash(text)
+        text.gsub(/&#8212;(?=\S)/, '--')
+      end
+
+      # @group Syntax Highlighting Source Code
+
+      # Syntax highlights +source+ in language +type+.
+      #
+      # @note To support a specific language +type+, implement the method
+      #   +html_syntax_highlight_TYPE+ in this class.
+      #
+      # @param [String] source the source code to highlight
+      # @param [Symbol] type the language type (:ruby, :plain, etc). Use
+      #   :plain for no syntax highlighting.
+      # @return [String] the highlighted source
+      def html_syntax_highlight(source, type = nil)
+        return "" unless source
+        return "{{{\n#{source}\n}}}"
+      end
+
+      # @return [String] unhighlighted source
+      def html_syntax_highlight_plain(source)
+        return "" unless source
+        return "{{{\n#{source}\n}}}"
+      end
+
+      # @group Linking Objects and URLs
+
+      # Resolves any text in the form of +{Name}+ to the object specified by
+      # Name. Also supports link titles in the form +{Name title}+.
+      #
+      # @example Linking to an instance method
+      #   resolve_links("{MyClass#method}") # => "<a href='...'>MyClass#method</a>"
+      # @example Linking to a class with a title
+      #   resolve_links("{A::B::C the C class}") # => "<a href='...'>the c class</a>"
+      # @param [String] text the text to resolve links in
+      # @return [String] HTML with linkified references
+      def resolve_links(text)
+        code_tags = 0
+        text.gsub(/<(\/)?(pre|code|tt)|\{(\S+?)(?:\s(.*?\S))?\}(?=[\W<]|.+<\/|$)/) do |str|
+          closed, tag, name, title, match = $1, $2, $3, $4, $&
+          if tag
+            code_tags += (closed ? -1 : 1)
+            next str
+          end
+          next str unless code_tags == 0
+
+          next(match) if name[0,1] == '|'
+          if object.is_a?(String)
+            object
+          else
+            link = linkify(name, title)
+            if link == name || link == title
+              match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text)
+              file = (@file ? @file : object.file) || '(unknown)'
+              line = (@file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0)
+              log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".")
+              log.warn((match[1] ? '...' : '') + match[2].gsub("\n","") + (match[3] ? '...' : '')) if match
+            end
+
+            link
+          end
+        end
+      end
+
+      def unlink(value)
+        value.gsub(/\b(([A-Z][a-z]+){2,99})\b/, "!\\1")
+      end
+
+      # (see BaseHelper#link_file)
+      def link_file(filename, title = nil, anchor = nil)
+        link_url(url_for_file(filename, anchor), title)
+      end
+
+      # (see BaseHelper#link_include_object)
+      def link_include_object(obj)
+        htmlify(obj.docstring)
+      end
+
+      # (see BaseHelper#link_object)
+      def link_object(obj, otitle = nil, anchor = nil, relative = true)
+        return otitle if obj.nil?
+        obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String)
+        if !otitle && obj.root?
+          title = "Top Level Namespace"
+        elsif otitle
+          # title = "`" + otitle.to_s + "`"
+          title = otitle.to_s
+        elsif object.is_a?(CodeObjects::Base)
+          # title = "`" + h(object.relative_path(obj)) + "`"
+          title = h(object.relative_path(obj))
+        else
+          # title = "`" + h(obj.to_s) + "`"
+          title = h(obj.to_s)
+        end
+        unless serializer
+          return unlink(title)
+        end
+        return unlink(title) if obj.is_a?(CodeObjects::Proxy)
+
+        link = url_for(obj, anchor, relative)
+        if link
+          link_url(link, title, :formatted => false)
+        else
+          unlink(title)
+        end
+      end
+
+      # (see BaseHelper#link_url)
+      def link_url(url, title = nil, params = {})
+        title ||= url
+        if url.to_s == ""
+          title
+        else
+          if params[:formatted]
+            "<a href=\"#{url}\">#{title}</a>"
+          else
+            "[#{url} #{title}]"
+          end
+        end
+      end
+
+      # @group URL Helpers
+
+      # @param [CodeObjects::Base] object the object to get an anchor for
+      # @return [String] the anchor for a specific object
+      def anchor_for(object)
+        # Method:_Google::APIClient#execute!
+        case object
+        when CodeObjects::MethodObject
+          if object.scope == :instance
+            "Method:_#{object.path}"
+          elsif object.scope == :class
+            "Method:_#{object.path}"
+          end
+        when CodeObjects::ClassVariableObject
+          "#{object.name.to_s.gsub('@@', '')}-#{object.type}"
+        when CodeObjects::Base
+          "#{object.name}-#{object.type}"
+        when CodeObjects::Proxy
+          object.path
+        else
+          object.to_s
+        end
+      end
+
+      # Returns the URL for an object.
+      #
+      # @param [String, CodeObjects::Base] obj the object (or object path) to link to
+      # @param [String] anchor the anchor to link to
+      # @param [Boolean] relative use a relative or absolute link
+      # @return [String] the URL location of the object
+      def url_for(obj, anchor = nil, relative = true)
+        link = nil
+        return link unless serializer
+        if obj.kind_of?(CodeObjects::Base) && obj.root?
+          return 'TopLevelNamespace'
+        end
+
+        if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
+          # If the obj is not a namespace obj make it the anchor.
+          anchor, obj = obj, obj.namespace
+        end
+
+        objpath = serializer.serialized_path(obj)
+        return link unless objpath
+
+        if relative
+          fromobj = object
+          if object.is_a?(CodeObjects::Base) &&
+              !object.is_a?(CodeObjects::NamespaceObject)
+            fromobj = fromobj.namespace
+          end
+
+          from = serializer.serialized_path(fromobj)
+          link = File.relative_path(from, objpath)
+        else
+          link = objpath
+        end
+
+        return (
+          link.gsub(/\.html$/, '').gsub(/\.wiki$/, '') +
+          (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
+        )
+      end
+
+      # Returns the URL for a specific file
+      #
+      # @param [String] filename the filename to link to
+      # @param [String] anchor optional anchor
+      # @return [String] the URL pointing to the file
+      def url_for_file(filename, anchor = nil)
+        fromobj = object
+        if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
+          fromobj = fromobj.namespace
+        end
+        from = serializer.serialized_path(fromobj)
+        if filename == options[:readme]
+          filename = 'Documentation'
+        else
+          filename = File.basename(filename).gsub(/\.[^.]+$/, '').capitalize
+        end
+        link = File.relative_path(from, filename)
+        return (
+          link.gsub(/\.html$/, '').gsub(/\.wiki$/, '') +
+          (anchor ? '#' + urlencode(anchor) : '')
+        )
+      end
+
+      # @group Formatting Objects and Attributes
+
+      # Formats a list of objects and links them
+      # @return [String] a formatted list of objects
+      def format_object_name_list(objects)
+        objects.sort_by {|o| o.name.to_s.downcase }.map do |o|
+          "<span class='name'>" + linkify(o, o.name) + "</span>"
+        end.join(", ")
+      end
+
+      # Formats a list of types from a tag.
+      #
+      # @param [Array<String>, FalseClass] typelist
+      #   the list of types to be formatted.
+      #
+      # @param [Boolean] brackets omits the surrounding
+      #   brackets if +brackets+ is set to +false+.
+      #
+      # @return [String] the list of types formatted
+      #   as [Type1, Type2, ...] with the types linked
+      #   to their respective descriptions.
+      #
+      def format_types(typelist, brackets = true)
+        return unless typelist.is_a?(Array)
+        list = typelist.map do |type|
+          type = type.gsub(/([<>])/) { h($1) }
+          type = type.gsub(/([\w:]+)/) do
+            $1 == "lt" || $1 == "gt" ? "`#{$1}`" : linkify($1, $1)
+          end
+        end
+        list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
+      end
+
+      # Get the return types for a method signature.
+      #
+      # @param [CodeObjects::MethodObject] meth the method object
+      # @param [Boolean] link whether to link the types
+      # @return [String] the signature types
+      # @since 0.5.3
+      def signature_types(meth, link = true)
+        meth = convert_method_to_overload(meth)
+
+        type = options[:default_return] || ""
+        if meth.tag(:return) && meth.tag(:return).types
+          types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
+          first = link ? h(types.first) : format_types([types.first], false)
+          if types.size == 2 && types.last == 'nil'
+            type = first + '<sup>?</sup>'
+          elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
+            type = first + '<sup>+</sup>'
+          elsif types.size > 2
+            type = [first, '...'].join(', ')
+          elsif types == ['void'] && options[:hide_void_return]
+            type = ""
+          else
+            type = link ? h(types.join(", ")) : format_types(types, false)
+          end
+        elsif !type.empty?
+          type = link ? h(type) : format_types([type], false)
+        end
+        type = "(#{type.to_s.strip}) " unless type.empty?
+        type
+      end
+
+      # Formats the signature of method +meth+.
+      #
+      # @param [CodeObjects::MethodObject] meth the method object to list
+      #   the signature of
+      # @param [Boolean] link whether to link the method signature to the details view
+      # @param [Boolean] show_extras whether to show extra meta-data (visibility, attribute info)
+      # @param [Boolean] full_attr_name whether to show the full attribute name
+      #   ("name=" instead of "name")
+      # @return [String] the formatted method signature
+      def signature(meth, link = true, show_extras = true, full_attr_name = true)
+        meth = convert_method_to_overload(meth)
+
+        type = signature_types(meth, link)
+        name = full_attr_name ? meth.name : meth.name.to_s.gsub(/^(\w+)=$/, '\1')
+        blk = format_block(meth)
+        args = !full_attr_name && meth.writer? ? "" : format_args(meth)
+        extras = []
+        extras_text = ''
+        if show_extras
+          if rw = meth.attr_info
+            attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
+            attname = attname.size == 1 ? attname.join('') + 'only' : nil
+            extras << attname if attname
+          end
+          extras << meth.visibility if meth.visibility != :public
+          extras_text = ' <span class="extras">(' + extras.join(", ") + ')</span>' unless extras.empty?
+        end
+        title = "%s *`%s`* `%s` `%s`" % [type, h(name.to_s).strip, args, blk]
+        title.gsub!(/<tt>/, "")
+        title.gsub!(/<\/tt>/, "")
+        title.gsub!(/`\s*`/, "")
+        title.strip!
+        if link
+          if meth.is_a?(YARD::CodeObjects::MethodObject)
+            link_title =
+              "#{h meth.name(true)} (#{meth.scope} #{meth.type})"
+          else
+            link_title = "#{h name} (#{meth.type})"
+          end
+          # This has to be raw HTML, can't wiki-format a link title otherwise.
+          "<a href=\"#{url_for(meth)}\">#{title}</a>#{extras_text}"
+        else
+          title + extras_text
+        end
+      end
+
+      # @group Getting the Character Encoding
+
+      # Returns the current character set. The default value can be overridden
+      # by setting the +LANG+ environment variable or by overriding this
+      # method. In Ruby 1.9 you can also modify this value by setting
+      # +Encoding.default_external+.
+      #
+      # @return [String] the current character set
+      # @since 0.5.4
+      def charset
+        return 'utf-8' unless RUBY19 || lang = ENV['LANG']
+        if RUBY19
+          lang = Encoding.default_external.name.downcase
+        else
+          lang = lang.downcase.split('.').last
+        end
+        case lang
+        when "ascii-8bit", "us-ascii", "ascii-7bit"; 'iso-8859-1'
+        else; lang
+        end
+      end
+
+      # @endgroup
+
+      private
+
+      # Converts a set of hash options into HTML attributes for a tag
+      #
+      # @param [Hash{String => String}] opts the tag options
+      # @return [String] the tag attributes of an HTML tag
+      def tag_attrs(opts = {})
+        opts.sort_by {|k, v| k.to_s }.map {|k,v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
+      end
+
+      # Converts a {CodeObjects::MethodObject} into an overload object
+      # @since 0.5.3
+      def convert_method_to_overload(meth)
+        # use first overload tag if it has a return type and method itself does not
+        if !meth.tag(:return) && meth.tags(:overload).size == 1 && meth.tag(:overload).tag(:return)
+          return meth.tag(:overload)
+        end
+        meth
+      end
+    end
+  end
+end

yard/templates/default/class/setup.rb

@@ -0,0 +1,43 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../../lib'))
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+require 'yard-google-code'
+
+include T('default/module')
+
+def init
+  super
+  sections.place(:subclasses).before(:children)
+  sections.place(:constructor_details, [T('method_details')]).before(:methodmissing)
+  # Weird bug w/ doubled sections
+  sections.uniq!
+end
+
+def constructor_details
+  ctors = object.meths(:inherited => true, :included => true)
+  return unless @ctor = ctors.find {|o| o.name == :initialize }
+  return if prune_method_listing([@ctor]).empty?
+  erb(:constructor_details)
+end
+
+def subclasses
+  return if object.path == "Object" # don't show subclasses for Object
+  unless globals.subclasses
+    globals.subclasses = {}
+    list = run_verifier Registry.all(:class)
+    list.each do |o|
+      (globals.subclasses[o.superclass.path] ||= []) << o if o.superclass
+    end
+  end
+
+  @subclasses = globals.subclasses[object.path]
+  return if @subclasses.nil? || @subclasses.empty?
+  @subclasses = @subclasses.sort_by {|o| o.path }.map do |child|
+    name = child.path
+    if object.namespace
+      name = object.relative_path(child)
+    end
+    [name, child]
+  end
+  erb(:subclasses)
+end

yard/templates/default/docstring/setup.rb

@@ -0,0 +1,54 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../../lib'))
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+require 'yard-google-code'
+
+def init
+  return if object.docstring.blank? && !object.has_tag?(:api)
+  sections :index, [:private, :deprecated, :abstract, :todo, :note, :returns_void, :text], T('tags')
+end
+
+def private
+  return unless object.has_tag?(:api) && object.tag(:api).text == 'private'
+  erb(:private)
+end
+
+def abstract
+  return unless object.has_tag?(:abstract)
+  erb(:abstract)
+end
+
+def deprecated
+  return unless object.has_tag?(:deprecated)
+  erb(:deprecated)
+end
+
+def todo
+  return unless object.has_tag?(:todo)
+  erb(:todo)
+end
+
+def note
+  return unless object.has_tag?(:note)
+  erb(:note)
+end
+
+def returns_void
+  return unless object.type == :method
+  return if object.name == :initialize && object.scope == :instance
+  return unless object.tags(:return).size == 1 && object.tag(:return).types == ['void']
+  erb(:returns_void)
+end
+
+def docstring_text
+  text = ""
+  unless object.tags(:overload).size == 1 && object.docstring.empty?
+    text = object.docstring
+  end
+
+  if text.strip.empty? && object.tags(:return).size == 1 && object.tag(:return).text
+    text = object.tag(:return).text.gsub(/\A([a-z])/) {|x| x.upcase }
+  end
+
+  text.strip
+end

yard/templates/default/method/setup.rb

@@ -0,0 +1,8 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../../lib'))
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+require 'yard-google-code'
+
+def init
+  sections :header, [T('method_details')]
+end

yard/templates/default/method_details/setup.rb

@@ -0,0 +1,8 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../../lib'))
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+require 'yard-google-code'
+
+def init
+  sections :header, [:method_signature, T('docstring')]
+end

yard/templates/default/module/setup.rb

@@ -0,0 +1,133 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../../lib'))
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+require 'yard-google-code'
+
+include Helpers::ModuleHelper
+
+def init
+  sections :header, :box_info, :pre_docstring, T('docstring'), :children,
+    :constant_summary, [T('docstring')], :inherited_constants,
+    :inherited_methods,
+    :methodmissing, [T('method_details')],
+    :attribute_details, [T('method_details')],
+    :method_details_list, [T('method_details')]
+end
+
+def pre_docstring
+  return if object.docstring.blank?
+  erb(:pre_docstring)
+end
+
+def children
+  @inner = [[:modules, []], [:classes, []]]
+  object.children.each do |child|
+    @inner[0][1] << child if child.type == :module
+    @inner[1][1] << child if child.type == :class
+  end
+  @inner.map! {|v| [v[0], run_verifier(v[1].sort_by {|o| o.name.to_s })] }
+  return if (@inner[0][1].size + @inner[1][1].size) == 0
+  erb(:children)
+end
+
+def methodmissing
+  mms = object.meths(:inherited => true, :included => true)
+  return unless @mm = mms.find {|o| o.name == :method_missing && o.scope == :instance }
+  erb(:methodmissing)
+end
+
+def method_listing(include_specials = true)
+  return @smeths ||= method_listing.reject {|o| special_method?(o) } unless include_specials
+  return @meths if @meths
+  @meths = object.meths(:inherited => false, :included => false)
+  @meths = sort_listing(prune_method_listing(@meths))
+  @meths
+end
+
+def special_method?(meth)
+  return true if meth.name(true) == '#method_missing'
+  return true if meth.constructor?
+  false
+end
+
+def attr_listing
+  return @attrs if @attrs
+  @attrs = []
+  [:class, :instance].each do |scope|
+    object.attributes[scope].each do |name, rw|
+      @attrs << (rw[:read] || rw[:write])
+    end
+  end
+  @attrs = sort_listing(prune_method_listing(@attrs, false))
+end
+
+def constant_listing
+  return @constants if @constants
+  @constants = object.constants(:included => false, :inherited => false)
+  @constants += object.cvars
+  @constants = run_verifier(@constants)
+  @constants
+end
+
+def sort_listing(list)
+  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
+end
+
+def docstring_full(obj)
+  docstring = ""
+  if obj.tags(:overload).size == 1 && obj.docstring.empty?
+    docstring = obj.tag(:overload).docstring
+  else
+    docstring = obj.docstring
+  end
+
+  if docstring.summary.empty? && obj.tags(:return).size == 1 && obj.tag(:return).text
+    docstring = Docstring.new(obj.tag(:return).text.gsub(/\A([a-z])/) {|x| x.upcase }.strip)
+  end
+
+  docstring
+end
+
+def docstring_summary(obj)
+  docstring_full(obj).summary
+end
+
+def groups(list, type = "Method")
+  if groups_data = object.groups
+    others = list.select {|m| !m.group }
+    groups_data.each do |name|
+      items = list.select {|m| m.group == name }
+      yield(items, name) unless items.empty?
+    end
+  else
+    others = []
+    group_data = {}
+    list.each do |meth|
+      if meth.group
+        (group_data[meth.group] ||= []) << meth
+      else
+        others << meth
+      end
+    end
+    group_data.each {|group, items| yield(items, group) unless items.empty? }
+  end
+
+  scopes(others) {|items, scope| yield(items, "#{scope.to_s.capitalize} #{type} Summary") }
+end
+
+def scopes(list)
+  [:class, :instance].each do |scope|
+    items = list.select {|m| m.scope == scope }
+    yield(items, scope) unless items.empty?
+  end
+end
+
+def mixed_into(object)
+  unless globals.mixed_into
+    globals.mixed_into = {}
+    list = run_verifier Registry.all(:class, :module)
+    list.each {|o| o.mixins.each {|m| (globals.mixed_into[m.path] ||= []) << o } }
+  end
+
+  globals.mixed_into[object.path] || []
+end

yard/templates/default/tags/setup.rb

@@ -0,0 +1,55 @@
+lib_dir = File.expand_path(File.join(File.dirname(__FILE__), '../../../lib'))
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.uniq!
+require 'yard-google-code'
+
+def init
+  tags = Tags::Library.visible_tags - [:abstract, :deprecated, :note, :todo]
+  create_tag_methods(tags - [:example, :option, :overload, :see])
+  sections :index, tags
+  sections.any(:overload).push(T('docstring'))
+end
+
+def return
+  if object.type == :method
+    return if object.name == :initialize && object.scope == :instance
+    return if object.tags(:return).size == 1 && object.tag(:return).types == ['void']
+  end
+  tag(:return)
+end
+
+private
+
+def tag(name, opts = nil)
+  return unless object.has_tag?(name)
+  opts ||= options_for_tag(name)
+  @no_names = true if opts[:no_names]
+  @no_types = true if opts[:no_types]
+  @name = name
+  out = erb('tag')
+  @no_names, @no_types = nil, nil
+  out
+end
+
+def create_tag_methods(tags)
+  tags.each do |tag|
+    next if respond_to?(tag)
+    instance_eval(<<-eof, __FILE__, __LINE__ + 1)
+      def #{tag}; tag(#{tag.inspect}) end
+    eof
+  end
+end
+
+def options_for_tag(tag)
+  opts = {:no_types => true, :no_names => true}
+  case Tags::Library.factory_method_for(tag)
+  when :with_types
+    opts[:no_types] = false
+  when :with_types_and_name
+    opts[:no_types] = false
+    opts[:no_names] = false
+  when :with_name
+    opts[:no_names] = false
+  end
+  opts
+end