yard 0.9.0 → 0.9.1

data/lib/yard/rubygems/hook.rb

@@ -0,0 +1,164 @@
+require 'rubygems'
+require 'rubygems/user_interaction'
+require 'fileutils'
+
+##
+# Gem::YARDoc provides methods to generate YARDoc and yri data for installed gems
+# upon gem installation.
+#
+# This file is automatically required by RubyGems 1.9 and newer.
+
+module YARD
+  class RubygemsHook
+
+    include Gem::UserInteraction
+    extend Gem::UserInteraction
+
+    @yard_version = nil
+
+    ##
+    # Force installation of documentation?
+
+    attr_accessor :force
+
+    ##
+    # Generate yard?
+
+    attr_accessor :generate_yard
+
+    ##
+    # Generate yri data?
+
+    attr_accessor :generate_yri
+
+    class << self
+
+      ##
+      # Loaded version of YARD. Set by ::load_yard
+
+      attr_reader :yard_version
+
+    end
+
+    ##
+    # Post installs hook that generates documentation for each specification in
+    # +specs+
+
+    def self.generation_hook(installer, specs)
+      start = Time.now
+      types = installer.document
+
+      generate_yard = types.include?('yardoc') || types.include?('yard')
+      generate_yri = types.include? 'yri'
+
+      specs.each do |spec|
+        new(spec, generate_yard, generate_yri).generate
+      end
+
+      return unless generate_yard or generate_yri
+
+      duration = (Time.now - start).to_i
+      names = specs.map(&:name).join ', '
+
+      say "Done installing documentation for #{names} after #{duration} seconds"
+    end
+
+    ##
+    # Loads the YARD generator
+
+    def self.load_yard
+      return if @yard_version
+
+      require 'yard'
+
+      @yard_version = Gem::Version.new ::YARD::VERSION
+    end
+
+    def initialize(spec, generate_yard = false, generate_yri = true)
+      @doc_dir = spec.doc_dir
+      @force = false
+      @spec = spec
+
+      @generate_yard = generate_yard
+      @generate_yri = generate_yri
+
+      @yard_dir = spec.doc_dir('yard')
+      @yri_dir = spec.doc_dir('.yardoc')
+    end
+
+    def run_yardoc(*args)
+      args << '--quiet' unless Gem.configuration.really_verbose
+      args << '--backtrace' if Gem.configuration.backtrace
+      unless File.file?(File.join(@spec.full_gem_path, '.yardopts'))
+        args << @spec.require_paths
+        if @spec.extra_rdoc_files.size > 0
+          args << '-'
+          args += @spec.extra_rdoc_files
+        end
+      end
+      args = args.flatten.map {|arg| arg.to_s }
+
+      Dir.chdir(@spec.full_gem_path) do
+        YARD::CLI::Yardoc.run(*args)
+      end
+    rescue Errno::EACCES => e
+      dirname = File.dirname e.message.split("-")[1].strip
+      raise Gem::FilePermissionError.new(dirname)
+    rescue => ex
+      alert_error "While generating documentation for #{@spec.full_name}"
+      ui.errs.puts "... MESSAGE:   #{ex}"
+      ui.errs.puts "... YARDOC args: #{args.join(' ')}"
+      ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
+      ui.errs.puts "(continuing with the rest of the installation)"
+    end
+
+    def install_yard
+      FileUtils.rm_rf @yard_dir
+
+      say "Installing YARD documentation for #{@spec.full_name}..."
+      run_yardoc '-o', @yard_dir
+    end
+
+    def install_yri
+      FileUtils.rm_rf @yri_dir
+
+      say "Building YARD (yri) index for #{@spec.full_name}..."
+      run_yardoc '-c', '-n', '--db', @yri_dir
+    end
+
+    ##
+    # Generates YARD and yri data
+
+    def generate
+      return if @spec.default_gem?
+      return unless @generate_yri || @generate_yard
+
+      setup
+
+      if @generate_yri && (@force || !File.exist?(@yri_dir))
+        install_yri
+      end
+
+      if @generate_yard && (@force || !File.exist?(@yard_dir))
+        install_yard
+      end
+    end
+
+    ##
+    # Prepares the spec for documentation generation
+
+    def setup
+      self.class.load_yard
+
+      if File.exist?(@doc_dir)
+        unless File.writable?(@doc_dir)
+          raise Gem::FilePermissionError, @doc_dir
+        end
+      else
+        FileUtils.mkdir_p @doc_dir
+      end
+    end
+  end
+end
+
+Gem.done_installing(&YARD::RubygemsHook.method(:generation_hook))

data/lib/yard/server.rb

@@ -5,7 +5,8 @@ module YARD
     # @return [void]
     # @since 0.6.2
     def self.register_static_path(path)
-      Commands::StaticFileCommand::STATIC_PATHS.push(path)
+      static_paths = Commands::StaticFileCommand::STATIC_PATHS
+      static_paths.push(path) unless static_paths.include?(path)
     end
   end
 end

data/lib/yard/server/commands/root_request_command.rb

@@ -0,0 +1,27 @@
+module YARD
+  module Server
+    module Commands
+      # Serves requests from the root of the server
+      class RootRequestCommand < Base
+        def run
+          favicon?
+
+          self.body = "Could not find: #{request.path}"
+          self.status = 404
+        end
+
+        private
+
+        # Return an empty favicon.ico if it does not exist so that
+        # browsers don't complain.
+        def favicon?
+          return unless request.path == '/favicon.ico'
+          self.headers['Content-Type'] = 'image/png'
+          self.status = 200
+          self.body = ''
+          raise FinishRequest
+        end
+      end
+    end
+  end
+end

data/lib/yard/server/commands/static_file_command.rb

@@ -4,7 +4,7 @@ module YARD
   module Server
     module Commands
       # Serves static content when no other router matches a request
-      class StaticFileCommand < Base
+      class StaticFileCommand < LibraryCommand
         include WEBrick::HTTPUtils
 
         DefaultMimeTypes['js'] = 'text/javascript'
@@ -17,7 +17,6 @@ module YARD
 
         def run
           assets_template = Templates::Engine.template(:default, :fulldoc, :html)
-          path = File.cleanpath(request.path).gsub(%r{^(../)+}, '')
 
           file = nil
           ([adapter.document_root] + STATIC_PATHS.reverse).compact.each do |path_prefix|
@@ -30,27 +29,15 @@ module YARD
           file ||= assets_template.find_file(path)
 
           if file
-            ext = "." + (request.path[/\.(\w+)$/, 1] || "html")
+            ext = "." + (path[/\.(\w+)$/, 1] || "html")
             headers['Content-Type'] = mime_type(ext, DefaultMimeTypes)
             self.body = File.read(file)
             return
           end
 
-          favicon?
+          self.body = "Could not find: #{request.path}"
           self.status = 404
         end
-
-        private
-
-        # Return an empty favicon.ico if it does not exist so that
-        # browsers don't complain.
-        def favicon?
-          return unless request.path == '/favicon.ico'
-          self.headers['Content-Type'] = 'image/png'
-          self.status = 200
-          self.body = ''
-          raise FinishRequest
-        end
       end
     end
   end

data/lib/yard/server/doc_server_helper.rb

@@ -10,7 +10,7 @@ module YARD
       def url_for(obj, anchor = nil, relative = false)
         return '' if obj.nil?
         return url_for_index if obj == '_index.html'
-        return "/#{obj}" if String === obj
+        return "/#{base_path(router.static_prefix)}/#{obj}" if String === obj
         url = super(obj, anchor, false)
         return unless url
         File.join('', base_path(router.docs_prefix), url)

data/lib/yard/server/router.rb

@@ -8,8 +8,8 @@ module YARD
     # options through {Adapter#initialize} or by directly modifying {Adapter#router}.
     #
     # The most general customization is to change the URL prefixes recognized by
-    # routing, which can be done by overriding {#docs_prefix}, {#list_prefix}
-    # and {#search_prefix}.
+    # routing, which can be done by overriding {#docs_prefix}, {#list_prefix},
+    # {#static_prefix}, and {#search_prefix}.
     #
     # == Implementing Custom Caching
     # By default, the Router class performs static disk-based caching on all
@@ -22,6 +22,7 @@ module YARD
     #   class MyRouter < YARD::Server::Router
     #     def docs_prefix; 'mydocs' end
     #     def list_prefix; 'mylist' end
+    #     def static_prefix; 'mystatic' end
     #     def search_prefix; 'mysearch' end
     #   end
     #
@@ -45,7 +46,7 @@ module YARD
       end
 
       # Perform routing on a specific request, serving the request as a static
-      # file through {Commands::StaticFileCommand} if no route is found.
+      # file through {Commands::RootRequestCommand} if no route is found.
       #
       # @param [Adapter Dependent] request the request object
       # @return [Array(Numeric,Hash,Array)] the Rack-style server response data
@@ -54,7 +55,7 @@ module YARD
         if result = (check_static_cache || route)
           result
         else
-          StaticFileCommand.new(adapter.options).call(request)
+          RootRequestCommand.new(adapter.options).call(request)
         end
       end
 
@@ -69,6 +70,9 @@ module YARD
       # @return [String] the URI prefix for all search requests
       def search_prefix; 'search' end
 
+      # @return [String] the URI prefix for all static assets (templates)
+      def static_prefix; 'static' end
+
       # @group Routing Methods
 
       # @return [Array(LibraryVersion, Array<String>)] the library followed
@@ -101,7 +105,7 @@ module YARD
         path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
         return route_index if path.empty? || path == docs_prefix
         case path
-        when /^(#{docs_prefix}|#{list_prefix}|#{search_prefix})(\/.*|$)/
+        when /^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_prefix})(\/.*|$)/
           prefix = $1
           paths = $2.gsub(%r{^/|/$}, '').split('/')
           library, paths = *parse_library_from_path(paths)
@@ -110,6 +114,7 @@ module YARD
           when docs_prefix;   route_docs(library, paths)
           when list_prefix;   route_list(library, paths)
           when search_prefix; route_search(library, paths)
+          when static_prefix; route_static(library, paths)
           end
         end
         nil
@@ -161,6 +166,10 @@ module YARD
         SearchCommand.new(final_options(library, paths)).call(request)
       end
 
+      def route_static(library, paths)
+        StaticFileCommand.new(final_options(library, paths)).call(request)
+      end
+
       # @group Utility Methods
 
       # Adds extra :library/:path option keys to the adapter options.
@@ -169,7 +178,8 @@ module YARD
       # @param (see #route_docs)
       # @return [Hash] finalized options
       def final_options(library, paths)
-        adapter.options.merge(:library => library, :path => paths.join('/'))
+        path = File.cleanpath(paths.join('/')).gsub(%r{^(\.\./)+}, '')
+        adapter.options.merge(:library => library, :path => path)
       end
     end
   end

data/lib/yard/tags/default_factory.rb

@@ -162,10 +162,12 @@ module YARD
           elsif c =~ /\S/ && level == 0
             break e = i if seen_space && list == ['']
             before << c
-          elsif c =~ /\s/ && level == 0 && !before.empty?
+          elsif c =~ /[ \t]/ && level == 0 && !before.empty?
             seen_space = true
           elsif level >= 1
             list.last << c
+          elsif level == 0 && c == "\n"
+            break e = i
           end
           last_seen = c
           i += 1

data/lib/yard/tags/directives.rb

@@ -408,6 +408,10 @@ module YARD
         obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
           parser.raw_text, parser.reference)
         handler.register_module_function(obj)
+        old_obj = parser.object
+        parser.object = obj
+        parser.post_process
+        parser.object = old_obj
         obj
       end
     end

data/lib/yard/templates/engine.rb

@@ -18,7 +18,7 @@ module YARD
         # @param [String] path a new template path
         # @return [void]
         def register_template_path(path)
-          template_paths.push path
+          template_paths.push(path) unless template_paths.include?(path)
         end
 
         # Creates a template module representing the path. Searches on disk

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

@@ -242,12 +242,17 @@ module YARD
           file = CodeObjects::ExtraFileObject.new(file)
         end
         file.attributes[:markup] ||= markup_for_file('', file.filename)
-        htmlify(file.contents, file.attributes[:markup] || options.markup)
+        insert_include(file.contents, file.attributes[:markup] || options.markup)
       end
 
       # (see BaseHelper#link_include_object)
       def link_include_object(obj)
-        htmlify(obj.docstring)
+        insert_include(obj.docstring)
+      end
+
+      # Inserts an include link while respecting inlining
+      def insert_include(text, markup = options.markup)
+        htmlify(text, markup).gsub(/\A\s*<p>|<\/p>\s*\Z/, '')
       end
 
       # (see BaseHelper#link_object)

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

@@ -9,6 +9,7 @@ module YARD
         # @return [Array<CodeObjects::Base>] a pruned list of methods
         def prune_method_listing(list, hide_attributes = true)
           list = run_verifier(list)
+          list = list.reject {|o| run_verifier([o.parent]).empty? }
           list = list.reject {|o| o.is_alias? unless CodeObjects::Proxy === o.namespace }
           list = list.reject {|o| o.is_attribute? unless CodeObjects::Proxy === o.namespace } if hide_attributes
           list

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

@@ -6,6 +6,7 @@ module YARD
         # @return [String] escapes text
         def h(text)
           out = ""
+          text = resolve_links(text)
           text = text.split(/\n/)
           text.each_with_index do |line, i|
             out <<
@@ -89,6 +90,17 @@ module YARD
           title = "%s%s%s %s%s%s" % [scope, name, args, blk, type, extras_text]
           title.gsub(/\s+/, ' ')
         end
+
+        private
+
+        def resolve_links(text)
+          text.gsub(/(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W]|$)/m) do |str|
+            escape, name, title, match = $1, $2, $3, $&
+            next(match[1..-1]) if escape
+            next(match) if name[0,1] == '|'
+            linkify(name, title)
+          end
+        end
       end
     end
   end

data/lib/yard/templates/template_options.rb

@@ -75,8 +75,8 @@ module YARD
       # @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 true if mixin == object # the method is not inherited
         return nil unless mixin.is_a?(CodeObjects::ModuleObject)
-        return nil if mixin == object # the method is not inherited
         embed_mixins.any? do |embed_mixin|
           re = /\A#{Regexp.quote(embed_mixin).gsub('\*', '.*')}\Z/
           matchstr = embed_mixin.include?("::") ? mixin.path : mixin.name