yard 0.7.5 → 0.8.0

data/lib/yard/templates/engine.rb

@@ -79,11 +79,11 @@ module YARD
         # @option options [Symbol] :template (:default) the default template
         # @return [String] the rendered template
         def render(options = {})
-          set_default_options(options)
-          mod = template(options[:template], options[:type], options[:format])
+          options = set_default_options(options)
+          mod = template(options.template, options.type, options.format)
 
-          if options[:serialize] != false
-            with_serializer(options[:object], options[:serializer]) { mod.run(options) }
+          if options.serialize != false
+            with_serializer(options.object, options.serializer) { mod.run(options) }
           else
             mod.run(options)
           end
@@ -98,9 +98,10 @@ module YARD
         # @param [Hash] options (see {render})
         # @return [void]
         def generate(objects, options = {})
-          set_default_options(options)
-          options[:objects] = objects
-          template(options[:template], :fulldoc, options[:format]).run(options)
+          options = set_default_options(options)
+          options.objects = objects
+          options.object = Registry.root
+          template(options.template, :fulldoc, options.format).run(options)
         end
 
         # Serializes the results of a block with a +serializer+ object.
@@ -130,10 +131,14 @@ module YARD
         # @option options [Symbol] :template (:default) the default template
         # @return [void]
         def set_default_options(options = {})
-          options[:__globals] ||= OpenStruct.new
-          options[:format] ||= :text
-          options[:type] ||= options[:object].type if options[:object]
-          options[:template] ||= :default
+          if options.is_a?(Hash)
+            options = TemplateOptions.new.tap do |o|
+              o.reset_defaults
+              o.update(options)
+            end
+          end
+          options.type ||= options.object.type if options.object
+          options
         end
 
         # Searches through the registered {template_paths} and returns
@@ -158,7 +163,7 @@ module YARD
 
         # The name of the module that represents a +path+
         #
-        # @param [String] the path toe generate a module name for
+        # @param [String] path the path to generate a module name for
         # @return [String] the module name
         def template_module_name(path)
           'Template_' + path.to_s.gsub(/[^a-z0-9]/i, '_')

data/lib/yard/templates/helpers/base_helper.rb

@@ -3,6 +3,12 @@ module YARD::Templates::Helpers
   module BaseHelper
     attr_accessor :object, :serializer
 
+    # @return [CodeObjects::Base] the object representing the current generated
+    #   page. Might not be the current {#object} when inside sub-templates.
+    attr_reader :owner
+    undef owner
+    def owner; @owner || object.namespace end
+
     # @group Managing Global Template State
 
     # An object that keeps track of global state throughout the entire template
@@ -10,7 +16,7 @@ module YARD::Templates::Helpers
     #
     # @return [OpenStruct] a struct object that stores state
     # @since 0.6.0
-    def globals; options[:__globals] end
+    def globals; options.globals end
 
     # @group Running the Verifier
 
@@ -21,7 +27,7 @@ module YARD::Templates::Helpers
     # @return [Array<CodeObjects::Base>] a list of code objects that match
     #   the verifier. If no verifier is supplied, all objects are returned.
     def run_verifier(list)
-      options[:verifier] ? options[:verifier].run(list) : list
+      options.verifier ? options.verifier.run(list) : list
     end
 
     # @group Escaping Text

data/lib/yard/templates/helpers/html_helper.rb

@@ -33,7 +33,7 @@ module YARD
       # @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])
+      def htmlify(text, markup = options.markup)
         markup_meth = "html_markup_#{markup}"
         return text unless respond_to?(markup_meth)
         return "" unless text
@@ -153,7 +153,7 @@ module YARD
       # @return [String] the highlighted source
       def html_syntax_highlight(source, type = nil)
         return "" unless source
-        return h(source) if options[:no_highlight]
+        return h(source) unless options.highlight
 
         new_type, source = parse_lang_for_codeblock(source)
         type ||= new_type || :ruby
@@ -196,6 +196,8 @@ module YARD
             title = nil if title.empty?
           end
 
+          name = CGI.unescapeHTML(name)
+
           if object.is_a?(String)
             object
           else
@@ -231,7 +233,7 @@ module YARD
           file = CodeObjects::ExtraFileObject.new(file)
         end
         file.attributes[:markup] ||= markup_for_file('', file.filename)
-        htmlify(file.contents, file.attributes[:markup] || options[:markup])
+        htmlify(file.contents, file.attributes[:markup] || options.markup)
       end
 
       # (see BaseHelper#link_include_object)
@@ -248,7 +250,14 @@ module YARD
         elsif otitle
           title = otitle.to_s
         elsif object.is_a?(CodeObjects::Base)
-          title = h(object.relative_path(obj))
+          # Check if we're linking to a class method in the current
+          # object. If we are, create a title in the format of
+          # "CurrentClass.method_name"
+          if obj.is_a?(CodeObjects::MethodObject) && obj.scope == :class && obj.parent == object
+            title = h([object.name, obj.sep, obj.name].join)
+          else
+            title = h(object.relative_path(obj))
+          end
         else
           title = h(obj.to_s)
         end
@@ -313,7 +322,7 @@ module YARD
           fromobj = object
           if object.is_a?(CodeObjects::Base) &&
               !object.is_a?(CodeObjects::NamespaceObject)
-            fromobj = fromobj.namespace
+            fromobj = owner
           end
 
           from = serializer.serialized_path(fromobj)
@@ -337,7 +346,7 @@ module YARD
           fromobj = fromobj.namespace
         end
         from = serializer.serialized_path(fromobj)
-        if filename == options[:readme]
+        if filename == options.readme
           path = 'index.html'
         else
           path = serializer.serialized_path(filename)
@@ -347,6 +356,39 @@ module YARD
         link
       end
 
+      # Returns the URL for a list type
+      #
+      # @param [String, Symbol] type the list type to generate a URL for
+      # @return [String] the URL pointing to the list
+      # @since 0.8.0
+      def url_for_list(type)
+        url_for_file("#{type}_list.html")
+      end
+
+      # Returns the URL for the frameset page
+      #
+      # @return [String] the URL pointing to the frames page
+      # @since 0.8.0
+      def url_for_frameset
+        url_for_file("frames.html")
+      end
+
+      # Returns the URL for the main page (README or alphabetic index)
+      #
+      # @return [String] the URL pointing to the first main page the
+      #   user should see.
+      def url_for_main
+        url_for_file("index.html")
+      end
+
+      # Returns the URL for the alphabetic index page
+      #
+      # @return [String] the URL pointing to the first main page the
+      #   user should see.
+      def url_for_index
+        url_for_file("_index.html")
+      end
+
       # @group Formatting Objects and Attributes
 
       # Formats a list of objects and links them
@@ -391,7 +433,7 @@ module YARD
           meth = meth.object
         end
 
-        type = options[:default_return] || ""
+        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)
@@ -401,7 +443,7 @@ module YARD
             type = first + '<sup>+</sup>'
           elsif types.size > 2
             type = [first, '...'].join(', ')
-          elsif types == ['void'] && options[:hide_void_return]
+          elsif types == ['void'] && options.hide_void_return
             type = ""
           else
             type = link ? h(types.join(", ")) : format_types(types, false)
@@ -449,7 +491,8 @@ module YARD
             link_title = "#{h name} (#{meth.type})"
           end
           obj = meth.respond_to?(:object) ? meth.object : meth
-          link_url(url_for(obj), title, :title => link_title) + extras_text
+          url = url_for(object, obj)
+          link_url(url, title, :title => link_title) + extras_text
         else
           title + extras_text
         end
@@ -506,9 +549,9 @@ module YARD
 
       # Parses !!!lang out of codeblock, returning the codeblock language
       # followed by the source code.
-      # 
+      #
       # @param [String] source the source code whose language to determine
-      # @return [Array(String, String)] the language, if any, and the 
+      # @return [Array(String, String)] the language, if any, and the
       #   remaining source
       # @since 0.7.5
       def parse_lang_for_codeblock(source)
@@ -519,10 +562,10 @@ module YARD
 
         [type, source]
       end
-      
+
       # Parses code blocks out of html and performs syntax highlighting
       # on code inside of the blocks.
-      # 
+      #
       # @param [String] html the html to search for code in
       # @return [String] highlighted html
       # @see #html_syntax_highlight
@@ -533,7 +576,7 @@ module YARD
           language, _ = parse_lang_for_codeblock(string)
           language ||= $1 || $2 || object.source_type
 
-          unless options[:no_highlight]
+          if options.highlight
             string = html_syntax_highlight(CGI.unescapeHTML(string), language)
           end
           classes = ['code', language].compact.join(' ')

data/lib/yard/templates/helpers/markup/rdoc_markup.rb

@@ -45,7 +45,7 @@ module YARD
             code_tags = 0
             text.gsub(/<(\/)?(pre|code|tt)|(\s|^|>)\+(?! )([^\n\+]{1,900})(?! )\+/) do |str|
               closed, tag, first_text, type_text, pre_text, no_match = $1, $2, $3, $4, $`, $&
-              
+
               if tag
                 code_tags += (closed ? -1 : 1)
                 next str

data/lib/yard/templates/helpers/markup_helper.rb

@@ -73,19 +73,19 @@ module YARD
       # found and exit the program.
       #
       # @return [Boolean] whether the markup provider was successfully loaded.
-      def load_markup_provider(type = options[:markup])
+      def load_markup_provider(type = options.markup)
         return true if MarkupHelper.markup_cache[type]
         MarkupHelper.markup_cache[type] ||= {}
 
         providers = MARKUP_PROVIDERS[type.to_sym]
         return true if providers && providers.empty?
-        if providers && options[:markup_provider]
-          providers = providers.select {|p| p[:lib] == options[:markup_provider] }
+        if providers && options.markup_provider
+          providers = providers.select {|p| p[:lib] == options.markup_provider }
         end
 
         if providers == nil || providers.empty?
           log.error "Invalid markup type '#{type}' or markup provider " +
-            "(#{options[:markup_provider]}) is not registered."
+            "(#{options.markup_provider}) is not registered."
           return false
         end
 
@@ -128,7 +128,7 @@ module YARD
         MARKUP_EXTENSIONS.each do |type, exts|
           return type if exts.include?(ext)
         end
-        options[:markup]
+        options.markup
       end
 
       # Strips any shebang lines on the file contents that pertain to
@@ -144,9 +144,9 @@ module YARD
       # Gets the markup provider class/module constant for a markup type
       # Call {#load_markup_provider} before using this method.
       #
-      # @param [Symbol] the markup type (:rdoc, :markdown, etc.)
+      # @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
       # @return [Class] the markup class
-      def markup_class(type = options[:markup])
+      def markup_class(type = options.markup)
         load_markup_provider(type)
         MarkupHelper.markup_cache[type][:class]
       end
@@ -154,9 +154,9 @@ module YARD
       # Gets the markup provider name for a markup type
       # Call {#load_markup_provider} before using this method.
       #
-      # @param [Symbol] the markup type (:rdoc, :markdown, etc.)
+      # @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
       # @return [Symbol] the markup provider name (usually the gem name of the library)
-      def markup_provider(type = options[:markup])
+      def markup_provider(type = options.markup)
         MarkupHelper.markup_cache[type][:provider]
       end
     end

data/lib/yard/templates/helpers/text_helper.rb

@@ -51,7 +51,7 @@ module YARD
             meth = meth.tag(:overload)
           end
 
-          type = options[:default_return] || ""
+          type = options.default_return || ""
           rmeth = meth
           if !rmeth.has_tag?(:return) && rmeth.respond_to?(:object)
             rmeth = meth.object
@@ -65,7 +65,7 @@ module YARD
               type = first + '+'
             elsif types.size > 2
               type = [first, '...'].join(', ')
-            elsif types == ['void'] && options[:hide_void_return]
+            elsif types == ['void'] && options.hide_void_return
               type = ""
             else
               type = types.join(", ")

data/lib/yard/templates/template.rb

@@ -7,17 +7,49 @@ module YARD
       attr_reader :options
 
       class << self
-        # @return [Array<Module>] a list of modules to be automatically included
+        # Extra includes are mixins that are included after a template is created. These
+        # mixins can be registered by plugins to operate on templates and override behaviour.
+        #
+        # Note that this array can be filled with modules or proc objects. If a proc object
+        # is given, the proc will be called with the {Template#options} hash containing
+        # relevant template information like the object, format, and more. The proc should
+        # return a module or nil if there is none.
+        #
+        # @example Adding in extra mixins to include on a template
+        #   Template.extra_includes << MyHelper
+        # @example Conditionally including a mixin if the format is html
+        #   Template.extra_includes << proc {|opts| MyHelper if opts.format == :html }
+        # @return [Array<Module, Proc>] a list of modules to be automatically included
         #   into any new template module
         attr_accessor :extra_includes
 
+        # @!parse extend ClassMethods
         # @private
         def included(klass)
           klass.extend(ClassMethods)
         end
+
+        # Includes the {extra_includes} modules into the template object.
+        #
+        # @param [Template] template the template object to mixin the extra includes.
+        # @param [SymbolHash] options the options hash containing all template information
+        # @return [void]
+        def include_extra(template, options)
+          extra_includes.each do |mod|
+            mod = mod.call(options) if mod.is_a?(Proc)
+            next unless mod.is_a?(Module)
+            template.extend(mod)
+          end
+        end
       end
 
-      self.extra_includes = []
+      self.extra_includes = [
+        proc {|options|
+          { :html => Helpers::HtmlHelper,
+            :text => Helpers::TextHelper,
+            :dot  => Helpers::UMLHelper }[options.format]
+        }
+      ]
 
       include ErbCache
       include Helpers::BaseHelper
@@ -131,16 +163,13 @@ module YARD
         end
       end
 
-      def initialize(opts = {})
+      def initialize(opts = TemplateOptions.new)
+        opts_class = opts.class
+        opts_class = TemplateOptions if opts_class == Hash
         @cache, @cache_filename = {}, {}
-        @sections, @options = [], {}
+        @sections, @options = [], opts_class.new
         add_options(opts)
-
-        extend(Helpers::HtmlHelper) if options[:format] == :html
-        extend(Helpers::TextHelper) if options[:format] == :text
-        extend(Helpers::UMLHelper) if options[:format] == :dot
-        extend(*Template.extra_includes) unless Template.extra_includes.empty?
-
+        Template.include_extra(self, options)
         init
       end
 
@@ -151,8 +180,8 @@ module YARD
       # @param [Array<String, Symbol>] path the path of the template
       # @return [Template] the loaded template module
       def T(*path)
-        path.unshift(options[:template]) if options[:template]
-        path.push(options[:format]) if options[:format]
+        path.unshift(options.template) if options.template
+        path.push(options.format) if options.format
         self.class.T(*path)
       end
 
@@ -299,7 +328,7 @@ module YARD
       end
 
       def erb_with(content, filename = nil)
-        erb = ERB.new(content, nil, options[:format] == :text ? '<>' : nil)
+        erb = ERB.new(content, nil, options.format == :text ? '<>' : nil)
         erb.filename = filename if filename
         erb
       end

data/lib/yard/templates/template_options.rb

@@ -0,0 +1,81 @@
+require 'ostruct'
+
+module YARD
+  module Templates
+    # An Options class containing default options for base template rendering. For
+    # options specific to generation of HTML output, see {CLI::YardocOptions}.
+    #
+    # @see CLI::YardocOptions
+    class TemplateOptions < YARD::Options
+      # @return [Symbol] the template output format
+      default_attr :format, :text
+
+      # @return [Symbol] the template name used to render output
+      default_attr :template, :default
+
+      # @return [Symbol] the markup format to use when parsing docstrings
+      default_attr :markup, :rdoc # default is :rdoc but falls back on :none
+
+      # @return [String] the default return type for a method with no return tags
+      default_attr :default_return, "Object"
+
+      # @return [Boolean] whether void methods should show "void" in their signature
+      default_attr :hide_void_return, false
+
+      # @return [Boolean] whether code blocks should be syntax highlighted
+      default_attr :highlight, true
+
+      # @return [Class] the markup provider class for the markup format
+      attr_accessor :markup_provider
+
+      # @return [OpenStruct] an open struct containing any global state across all
+      #   generated objects in a template.
+      default_attr :globals, lambda { OpenStruct.new }
+      alias __globals globals
+
+      # @return [CodeObjects::Base] the main object being generated in the template
+      attr_accessor :object
+
+      # @return [Symbol] the template type used to generate output
+      attr_accessor :type
+
+      # @return [Boolean] whether serialization should be performed
+      default_attr :serialize, false
+
+      # @return [Serializers::Base] the serializer used to generate links and serialize
+      #   output. Serialization output only occurs if {#serialize} is +true+.
+      attr_accessor :serializer
+
+      # @deprecated use {#highlight} instead.
+      # @return [Boolean] whether highlighting should be ignored
+      attr_reader :no_highlight
+      undef no_highlight
+      def no_highlight; !highlight end
+      def no_highlight=(value) self.highlight = !value end
+
+      # @return [String] the title of a given page
+      attr_accessor :page_title
+
+      # @example A list of mixin path names (including wildcards)
+      #   opts.embed_mixins #=> ['ClassMethods', '*Helper', 'YARD::*']
+      # @return [Array<String>] an array of module name wildcards to embed into
+      #   class documentation as if their methods were defined directly in the class.
+      #   Useful for modules like ClassMethods. If the name contains '::', the module
+      #   is matched against the full mixin path, otherwise only the module name is used.
+      default_attr :embed_mixins, lambda { [] }
+
+      # @param [CodeObjects::Base] mixin accepts any code object, but returns
+      #   nil unless the object is a module.
+      # @return [Boolean] whether a mixin matches the embed_mixins list
+      # @return [nil] if the mixin is not a module object
+      def embed_mixins_match?(mixin)
+        return nil unless mixin.is_a?(CodeObjects::ModuleObject)
+        embed_mixins.any? do |embed_mixin|
+          re = /\A#{Regexp.quote(embed_mixin).gsub('\*', '.*')}\Z/
+          matchstr = embed_mixin.include?("::") ? mixin.path : mixin.name
+          re.match(matchstr.to_s)
+        end
+      end
+    end
+  end
+end