yard 0.6.8 → 0.7.0

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

@@ -6,47 +6,47 @@ module YARD
       # This is the base command class used to implement custom commands for
       # a server. A command will be routed to by the {Router} class and return
       # a Rack-style response.
-      # 
+      #
       # == Attribute Initializers
       # All attributes can be initialized via options passed into the {#initialize}
-      # method. When creating a custom command, the {Adapter#options} will 
+      # method. When creating a custom command, the {Adapter#options} will
       # automatically be mapped to attributes by the same name on your class.
-      # 
+      #
       #   class MyCommand < Base
       #     attr_accessor :myattr
       #   end
-      # 
+      #
       #   Adapter.new(libs, {:myattr => 'foo'}).start
-      #   
+      #
       #   # when a request comes in, cmd.myattr == 'foo'
-      # 
+      #
       # == Subclassing Notes
       # To implement a custom command, override the {#run} method, not {#call}.
       # In your implementation, you should set the body and status for requests.
       # See details in the +#run+ method documentation.
-      # 
+      #
       # Note that if your command deals directly with libraries, you should
       # consider subclassing the more specific {LibraryCommand} class instead.
-      # 
+      #
       # @abstract
       # @see #run
       class Base
         # @group Basic Command and Adapter Options
-        
+
         # @return [Hash] the options passed to the command's constructor
         attr_accessor :command_options
-        
+
         # @return [Adapter] the server adapter
         attr_accessor :adapter
 
         # @return [Boolean] whether to cache
         attr_accessor :caching
-        
+
         # @group Attributes Set Per Request
 
         # @return [Request] request object
         attr_accessor :request
-        
+
         # @return [String] the path after the command base URI
         attr_accessor :path
 
@@ -58,13 +58,13 @@ module YARD
 
         # @return [String] the response body. Defaults to empty string.
         attr_accessor :body
-        
+
         # @group Instance Method Summary
 
-        # Creates a new command object, setting attributes named by keys 
+        # Creates a new command object, setting attributes named by keys
         # in the options hash. After initialization, the options hash
         # is saved in {#command_options} for further inspection.
-        # 
+        #
         # @example Creating a Command
         #   cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
         #   cmd.library # => mylib
@@ -79,7 +79,7 @@ module YARD
         end
 
         # The main method called by a router with a request object.
-        # 
+        #
         # @note This command should not be overridden by subclasses. Implement
         #   the callback method {#run} instead.
         # @param [Adapter Dependent] request the request object
@@ -101,13 +101,13 @@ module YARD
           not_found if status == 404
           [status, headers, body.is_a?(Array) ? body : [body]]
         end
-        
+
         # @group Abstract Methods
 
         # Subclass this method to implement a custom command. This method
-        # should set the {#status} and {#body}, and optionally modify the 
+        # should set the {#status} and {#body}, and optionally modify the
         # {#headers}. Note that +#status+ defaults to 200.
-        # 
+        #
         # @example A custom command
         #   class ErrorCommand < Base
         #     def run
@@ -116,7 +116,7 @@ module YARD
         #       self.headers['Conten-Type'] = 'text/plain'
         #     end
         #   end
-        #       
+        #
         # @abstract
         # @return [void]
         def run
@@ -124,12 +124,12 @@ module YARD
         end
 
         protected
-        
+
         # @group Helper Methods
-        
+
         # Renders a specific object if provided, or a regular template rendering
         # if object is not provided.
-        # 
+        #
         # @todo This method is dependent on +#options+, it should be in {LibraryCommand}.
         # @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if
         #   an object is provided, or {Templates::Engine.render} if object is nil. Both
@@ -145,9 +145,9 @@ module YARD
             cache object
           end
         end
-        
+
         # Override this method to implement custom caching mechanisms for
-        # 
+        #
         # @example Caching to memory
         #   $memory_cache = {}
         #   def cache(data)
@@ -169,7 +169,7 @@ module YARD
 
         # Sets the body and headers (but not status) for a 404 response. Does
         # nothing if the body is already set.
-        # 
+        #
         # @return [void]
         def not_found
           return unless body.empty?

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

@@ -2,7 +2,7 @@ module YARD
   module Server
     module Commands
       # Displays a README or extra file.
-      # 
+      #
       # @todo Implement better support for detecting binary (image) filetypes
       class DisplayFileCommand < LibraryCommand
         def run
@@ -13,7 +13,8 @@ module YARD
             headers['Content-Type'] = StaticFileCommand::DefaultMimeTypes[$1.downcase] || 'text/html'
             render IO.read(filename)
           else
-            options.update(:object => Registry.root, :type => :layout, :file => filename)
+            file = CodeObjects::ExtraFileObject.new(filename)
+            options.update(:object => Registry.root, :type => :layout, :file => file)
             render
           end
         end

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

@@ -5,7 +5,7 @@ module YARD
       class DisplayObjectCommand < LibraryCommand
         def run
           return index if path.empty?
-          
+
           if object = Registry.at(object_path)
             options.update(:type => :layout)
             render(object)
@@ -13,7 +13,7 @@ module YARD
             self.status = 404
           end
         end
-        
+
         def index
           Registry.load_all
 
@@ -29,14 +29,14 @@ module YARD
           )
           render
         end
-        
+
         def not_found
           super
           self.body = "Could not find object: #{object_path}"
         end
-        
+
         private
-        
+
         def object_path
           return @object_path if @object_path
           if path == "toplevel"

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

@@ -4,7 +4,7 @@ module YARD
       # Displays an object wrapped in frames
       class FramesCommand < DisplayObjectCommand
         include DocServerHelper
-        
+
         def run
           main_url = request.path.gsub(/^(.+)?\/frames(?:\/(#{path}))?$/, '\1/\2')
           if path =~ %r{^file/}

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

@@ -5,7 +5,7 @@ module YARD
       # Some commands do not, but most (like {DisplayObjectCommand}) do. If your
       # command deals with libraries directly, subclass this class instead.
       # See {Base} for notes on how to subclass a command.
-      # 
+      #
       # @abstract
       class LibraryCommand < Base
         # @return [LibraryVersion] the object containing library information
@@ -19,14 +19,14 @@ module YARD
 
         # @return [Boolean] whether router should route for multiple libraries
         attr_accessor :single_library
-        
-        # @return [Boolean] whether to reparse data 
+
+        # @return [Boolean] whether to reparse data
         attr_accessor :incremental
 
         # Needed to synchronize threads in {#setup_yardopts}
         # @private
         @@library_chdir_lock = Mutex.new
-        
+
         def initialize(opts = {})
           super
           self.serializer = DocServerSerializer.new(self)
@@ -48,7 +48,7 @@ module YARD
         rescue LibraryNotPreparedError
           not_prepared
         end
-        
+
         private
 
         def setup_library
@@ -84,13 +84,13 @@ module YARD
           Registry.load_yardoc(library.yardoc_file)
           Thread.current[:__yard_last_yardoc__] = library.yardoc_file
         end
-        
+
         def not_prepared
           self.caching = false
           options.update(:path => request.path, :template => :doc_server, :type => :processing)
           [302, {'Content-Type' => 'text/html'}, [render]]
         end
-        
+
         # @private
         @@last_yardoc = nil
       end

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

@@ -4,10 +4,10 @@ module YARD
       # Returns the index of libraries served by the server.
       class LibraryIndexCommand < Base
         attr_accessor :options
-        
+
         def run
           return unless path.empty?
-          
+
           self.options = SymbolHash.new(false).update(
             :markup => :rdoc,
             :format => :html,

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

@@ -4,40 +4,40 @@ module YARD
       # Returns a list of objects of a specific type
       class ListCommand < LibraryCommand
         include Templates::Helpers::BaseHelper
-        
+
         def items; raise NotImplementedError end
         def type; raise NotImplementedError end
 
         def run
-          options.update(:items => items, :template => :doc_server, 
+          options.update(:items => items, :template => :doc_server,
                          :list_type => request.path.split('/').last, :type => :full_list)
           render
         end
       end
-      
+
       # Returns the list of classes / modules in a library
       class ListClassesCommand < ListCommand
         def type; :class end
-        
+
         def items
           Registry.load_all
           run_verifier(Registry.all(:class, :module))
         end
       end
-      
+
       # Returns the list of methods in a library
       class ListMethodsCommand < ListCommand
         include Templates::Helpers::ModuleHelper
-        
+
         def type; :methods end
-        
+
         def items
           Registry.load_all
           items = Registry.all(:method).sort_by {|m| m.name.to_s }
           prune_method_listing(items)
         end
       end
-      
+
       # Returns the list of README/extra files in a library
       class ListFilesCommand < ListCommand
         def type; :files end

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

@@ -5,7 +5,7 @@ module YARD
       # the results as HTML or plaintext
       class SearchCommand < LibraryCommand
         attr_accessor :results, :query
-        
+
         def run
           Registry.load_all
           self.query = request.query['q']
@@ -16,16 +16,16 @@ module YARD
           search_for_object
           request.xhr? ? serve_xhr : serve_normal
         end
-        
+
         def visible_results
           results[0, 10]
         end
-        
+
         private
-        
+
         def serve_xhr
           self.headers['Content-Type'] = 'text/plain'
-          self.body = visible_results.map {|o| 
+          self.body = visible_results.map {|o|
             [(o.type == :method ? o.name(true) : o.name).to_s,
              o.path,
              o.namespace.root? ? '' : o.namespace.path,
@@ -33,7 +33,7 @@ module YARD
             ].join(",")
           }.join("\n")
         end
-        
+
         def serve_normal
           options.update(
             :visible_results => visible_results,
@@ -44,7 +44,7 @@ module YARD
           )
           self.body = Templates::Engine.render(options)
         end
-        
+
         def search_for_object
           splitquery = query.split(/\s+/).map {|c| c.downcase }.reject {|m| m.empty? }
           self.results = Registry.all.select {|o|
@@ -57,7 +57,7 @@ module YARD
                 !(query =~ /[#.]/) && query.include?("::")
               when :class, :module, :constant, :class_variable
                 query =~ /[#.]/
-              end 
+              end
             }.sort_by {|o|
               name = (o.type == :method ? o.name(true) : o.name).to_s
               name.length.to_f / query.length.to_f

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

@@ -17,7 +17,7 @@ module YARD
           File.join(YARD::TEMPLATE_ROOT, 'default', 'fulldoc', 'html'),
           File.join(File.dirname(__FILE__), '..', 'templates', 'default', 'fulldoc', 'html')
         ]
-        
+
         def run
           path = File.cleanpath(request.path).gsub(%r{^(../)+}, '')
           ([adapter.document_root] + STATIC_PATHS.reverse).compact.each do |path_prefix|
@@ -32,9 +32,9 @@ module YARD
           favicon?
           self.status = 404
         end
-        
+
         private
-        
+
         # Return an empty favicon.ico if it does not exist so that
         # browsers don't complain.
         def favicon?

data/lib/yard/server/doc_server_helper.rb

@@ -18,10 +18,13 @@ module YARD
       # @param (see Templates::Helpers::HtmlHelper#url_for_file)
       # @return (see Templates::Helpers::HtmlHelper#url_for_file)
       def url_for_file(filename, anchor = nil)
-        "/#{base_path(router.docs_prefix)}/file/" + filename.sub(%r{^#{@library.source_path.to_s}/}, '') + 
+        if filename.is_a?(CodeObjects::ExtraFileObject)
+          filename = filename.filename
+        end
+        "/#{base_path(router.docs_prefix)}/file/" + filename.sub(%r{^#{@library.source_path.to_s}/}, '') +
           (anchor ? "##{anchor}" : "")
       end
-      
+
       # @example The base path for a library 'foo'
       #   base_path('docs') # => 'docs/foo'
       # @param [String] path the path prefix for a base path URI
@@ -29,7 +32,7 @@ module YARD
       def base_path(path)
         path + (@single_library ? '' : "/#{@library}")
       end
-      
+
       # @return [Router] convenience method for accessing the router
       def router; @adapter.router end
     end

data/lib/yard/server/doc_server_serializer.rb

@@ -6,7 +6,7 @@ module YARD
     # static relative paths to files on disk.
     class DocServerSerializer < Serializers::FileSystemSerializer
       include WEBrick::HTTPUtils
-      
+
       def initialize(command)
         super(:command => command, :extension => '')
       end

data/lib/yard/server/library_version.rb

@@ -3,37 +3,37 @@ require 'fileutils'
 module YARD
   module Server
     # This exception is raised when {LibraryVersion#prepare!} fails, or discovers
-    # that the library is not "prepared" to be served by 
+    # that the library is not "prepared" to be served by
     class LibraryNotPreparedError < RuntimeError; end
-    
+
     # A library version encapsulates a library's documentation at a specific version.
     # Although the version is optional, this allows for creating multiple documentation
     # points for a specific library, each representing a unique version. The term
-    # "library" used in other parts of the YARD::Server documentation refers to 
+    # "library" used in other parts of the YARD::Server documentation refers to
     # objects of this class unless otherwise noted.
-    # 
+    #
     # A library points to a location where a {#yardoc_file} is located so that
     # its documentation may be loaded and served. Optionally, a {#source_path} is
-    # given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts}) 
-    # should be loaded from. Both of these methods may not be known immediately, 
-    # since the yardoc file may not be built until later. Resolving the yardoc 
+    # given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts})
+    # should be loaded from. Both of these methods may not be known immediately,
+    # since the yardoc file may not be built until later. Resolving the yardoc
     # file and source path are dependent on the specific library "source type" used.
     # Source types (known as "library source") are discussed in detail below.
-    # 
+    #
     # == Using with Adapters
     # A list of libraries need to be passed into adapters upon creation. In
     # most cases, you will never do this manually, but if you use a {RackMiddleware},
     # you will need to pass in this list yourself. To build this list of libraries,
     # you should create a hash of library names mapped to an *Array* of LibraryVersion
     # objects. For example:
-    # 
-    #   {'mylib' => [LibraryVersion.new('mylib', '1.0', ...), 
+    #
+    #   {'mylib' => [LibraryVersion.new('mylib', '1.0', ...),
     #                LibraryVersion.new('mylib', '2.0', ...)]}
-    # 
+    #
     # Note that you can also use {Adapter#add_library} for convenience.
-    # 
+    #
     # The "array" part is required, even for just one library version.
-    # 
+    #
     # == Library Sources
     # The {#source} method represents the library source type, ie. where the
     # library "comes from". It might come from "disk", or it might come from a
@@ -43,73 +43,73 @@ module YARD
     # is controlled through the {#prepare!} method, which prepares the yardoc file
     # given a specific library source. We will see how this works in detail in
     # the following section.
-    # 
+    #
     # == Implementing a Custom Library Source
-    # YARD can be extended to support custom library sources in order to 
+    # YARD can be extended to support custom library sources in order to
     # build or retrieve a yardoc file at runtime from many different locations.
-    # 
+    #
     # To implement this behaviour, two methods must be added to the +LibraryVersion+
     # class, +#load_yardoc_from_SOURCE+ and +#source_path_for_SOURCE+. In both
     # cases, "SOURCE" represents the source type used in {#source} when creating
     # the library object. The +#source_path_for_SOURCE+ method is called upon
-    # creation and should return the location where the source code for the library 
+    # creation and should return the location where the source code for the library
     # lives. The load method is called from {#prepare!} if there is no yardoc file
     # and should set {#yardoc_file}. Below is a full example for
     # implementing a custom library source, +:http+, which reads packaged .yardoc
     # databases from zipped archives off of an HTTP server.
-    # 
+    #
     # @example Implementing a Custom Library Source
     #   # Adds the source type "http" for .yardoc files zipped on HTTP servers
     #   class LibraryVersion
     #     def load_yardoc_from_http
     #       return if yardoc_file # we have the library
-    # 
+    #
     #       # otherwise download it in a thread and return immediately
-    #       Thread.new do 
+    #       Thread.new do
     #         # zip/unzip method implementations are not shown
     #         download_zip_file("http://mysite.com/yardocs/#{self}.zip")
     #         unzip_file_to("/path/to/yardocs/#{self}")
     #         self.yardoc_file = "/path/to/yardocs/#{self}/.yardoc"
     #         self.source_path = self.yardoc_file
     #       end
-    # 
+    #
     #       # tell the server it's not ready yet (but it might be next time)
     #       raise LibraryNotPreparedError
     #     end
-    # 
+    #
     #     # we set this later
     #     def source_path_for_http; nil end
     #   end
-    # 
+    #
     #   # Creating a library of this source type:
     #   LibraryVersion.new('name', '1.0', nil, :http)
-    # 
+    #
     class LibraryVersion
       # @return [String] the name of the library
       attr_accessor :name
-      
+
       # @return [String] the version of the specific library
       attr_accessor :version
-      
+
       # @return [String] the location of the yardoc file used to load the object
       #   information from.
       # @return [nil] if no yardoc file exists yet. In this case, {#prepare!} will
       #   be called on this library to build the yardoc file.
       attr_accessor :yardoc_file
-      
+
       # @return [Symbol] the source type representing where the yardoc should be
       #   loaded from. Defaults are +:disk+ and +:gem+, though custom sources
       #   may be implemented. This value is used to inform {#prepare!} about how
       #   to load the necessary data in order to display documentation for an object.
       # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
       attr_accessor :source
-      
+
       # @return [String] the location of the source code for a library. This
       #   value is filled by calling +#source_path_for_SOURCE+ on this class.
       # @return [nil] if there is no source code
       # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
       attr_accessor :source_path
-      
+
       # @param [String] name the name of the library
       # @param [String] version the specific (usually, but not always, numeric) library
       #   version
@@ -124,7 +124,7 @@ module YARD
         self.source = source
         self.source_path = load_source_path
       end
-      
+
       # @param [Boolean] url_format if true, returns the string in a URI-compatible
       #   format (for appending to a URL). Otherwise, it is given in a more human
       #   readable format.
@@ -132,29 +132,29 @@ module YARD
       def to_s(url_format = true)
         version ? "#{name}#{url_format ? '/' : '-'}#{version}" : "#{name}"
       end
-      
+
       # @return [Fixnum] used for Hash mapping.
       def hash; to_s.hash end
-      
+
       # @return [Boolean] whether another LibraryVersion is equal to this one
       def eql?(other)
-        other.is_a?(LibraryVersion) && other.name == name && 
+        other.is_a?(LibraryVersion) && other.name == name &&
           other.version == version && other.yardoc_file == yardoc_file
       end
       alias == eql?
       alias equal? eql?
-      
+
       # @note You should not directly override this method. Instead, implement
       #   +load_yardoc_from_SOURCENAME+ when implementing loading for a specific
       #   source type. See the {LibraryVersion} documentation for "Implementing
       #   a Custom Library Source"
-      # 
-      # Prepares a library to be displayed by the server. This callback is 
+      #
+      # Prepares a library to be displayed by the server. This callback is
       # performed before each request on a library to ensure that it is loaded
       # and ready to be viewed. If any steps need to be performed prior to loading,
       # they are performed through this method (though they should be implemented
       # through the +load_yardoc_from_SOURCE+ method).
-      # 
+      #
       # @raise [LibraryNotPreparedError] if the library is not ready to be
       #   displayed. Usually when raising this error, you would simultaneously
       #   begin preparing the library for subsequent requests, although this
@@ -164,7 +164,7 @@ module YARD
         meth = "load_yardoc_from_#{source}"
         send(meth) if respond_to?(meth)
       end
-      
+
       # @return [Gem::Specification] a gemspec object for a given library. Used
       #   for :gem source types.
       # @return [nil] if there is no installed gem for the library
@@ -172,7 +172,7 @@ module YARD
         ver = version ? "= #{version}" : ">= 0"
         Gem.source_index.find_name(name, ver).first
       end
-      
+
       protected
 
       # Called when a library of source type "disk" is to be prepared. In this
@@ -181,11 +181,11 @@ module YARD
       def load_yardoc_from_disk
         nil
       end
-      
+
       # Called when a library of source type "gem" is to be prepared. In this
       # case, the {#yardoc_file} needs to point to the correct location for
       # the installed gem. The yardoc file is built if it has not been done.
-      # 
+      #
       # @raise [LibraryNotPreparedError] if the gem does not have an existing
       #   yardoc file.
       def load_yardoc_from_gem
@@ -205,19 +205,19 @@ module YARD
           raise LibraryNotPreparedError
         end
       end
-      
+
       # @return [String] the source path for a disk source
       def source_path_for_disk
         File.dirname(yardoc_file) if yardoc_file
       end
-      
+
       # @return [String] the source path for a gem source
       def source_path_for_gem
         gemspec.full_gem_path if gemspec
       end
-      
+
       private
-      
+
       def load_source_path
         meth = "source_path_for_#{source}"
         send(meth) if respond_to?(meth)