class YARD::Server::LibraryVersion


LibraryVersion.new(‘name’, ‘1.0’, nil, :http)
# Creating a library of this source type:
end
end
File.dirname(yardoc_file)
def source_path_for_http
end
“/path/to/yardocs/#{self}/.yardoc”
def yardoc_file_for_http
end
raise LibraryNotPreparedError
# tell the server it’s not ready yet (but it might be next time)
end
unzip_file_to(“/path/to/yardocs/#{self}”)
download_zip_file(“mysite.com/yardocs/#{self}.zip”)
# zip/unzip method implementations are not shown
Thread.new do
def load_yardoc_from_http
class LibraryVersion
# Adds the source type “http” for .yardoc files zipped on HTTP servers
@example Implementing a Custom Library Source
{#yardoc_file=}) on the object at any time.
methods are optional and can be set manually (via {#source_path=} and
Note that only #load_yardoc_from_SOURCE is required. The other two
databases from zipped archives off of an HTTP server.
implementing a custom library source, :http, which reads packaged .yardoc
and should set {#yardoc_file}. Below is a full example for
lives. The load method is called from {#prepare!} if there is no yardoc file
creation and should return the location where the source code for the library
#yardoc_file_for_SOURCE and #source_path_for_SOURCE methods are called upon
type used in {#source} when creating the library object. The
#source_path_for_SOURCE. In all cases, “SOURCE” represents the source
class, #load_yardoc_from_SOURCE, #yardoc_file_for_SOURCE, and
To implement this behaviour, 3 methods can be added to the LibraryVersion
build or retrieve a yardoc file at runtime from many different locations.
YARD can be extended to support custom library sources in order to
== Implementing a Custom Library Source
the following section.
given a specific library source. We will see how this works in detail in
is controlled through the {#prepare!} method, which prepares the yardoc file
it may also be built dynamically if it does not yet exist. This behaviour
two cases, the yardoc file sits somewhere on your filesystem, though
“gem” (technically the disk, but a separate type nonetheless). In these
library “comes from”. It might come from “disk”, or it might come from a
The {#source} method represents the library source type, ie. where the
== Library Sources
The “array” part is required, even for just one library version.
Note that you can also use {Adapter#add_library} for convenience.
LibraryVersion.new(‘mylib’, ‘2.0’, …)]}
{‘mylib’ => [LibraryVersion.new(‘mylib’, ‘1.0’, …),
objects. For example:
you should create a hash of library names mapped to an Array of LibraryVersion
you will need to pass in this list yourself. To build this list of libraries,
most cases, you will never do this manually, but if you use a {RackMiddleware},
A list of libraries need to be passed into adapters upon creation. In
== Using with Adapters
Source types (known as “library source”) are discussed in detail below.
file and source path are dependent on the specific library “source type” used.
since the yardoc file may not be built until later. Resolving the yardoc
should be loaded from. Both of these methods may not be known immediately,
given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts})
its documentation may be loaded and served. Optionally, a {#source_path} is
A library points to a location where a {#yardoc_file} is located so that
objects of this class unless otherwise noted.
“library” used in other parts of the YARD::Server documentation refers to
points for a specific library, each representing a unique version. The term
Although the version is optional, this allows for creating multiple documentation
A library version encapsulates a library’s documentation at a specific version.

def eql?(other)

Returns:
  • (Boolean) - whether another LibraryVersion is equal to this one 
def eql?(other)
  other.is_a?(LibraryVersion) && other.name == name &&
    other.version == version && other.yardoc_file == yardoc_file
end

def gemspec

Returns:
  • (nil) - if there is no installed gem for the library
  • (Gem::Specification) - a gemspec object for a given library. Used 
def gemspec
  ver = version ? "= #{version}" : ">= 0"
  YARD::GemIndex.find_all_by_name(name, ver).last
end

def hash; to_s.hash end

Returns:
  • (Fixnum) - used for Hash mapping. 
def hash; to_s.hash end

def initialize(name, version = nil, yardoc = nil, source = :disk)

Parameters:
  • source (Symbol) -- the location of the files used to build the yardoc.
  • yardoc (String) -- the location of the yardoc file, or nil if it is
  • version (String) -- the specific (usually, but not always, numeric) library
  • name (String) -- the name of the library 
def initialize(name, version = nil, yardoc = nil, source = :disk)
  self.name = name
  self.yardoc_file = yardoc
  self.version = version
  self.source = source
end

def load_source_path 

def load_source_path
  meth = "source_path_for_#{source}"
  send(meth) if respond_to?(meth, true)
end

def load_yardoc_file 

def load_yardoc_file
  meth = "yardoc_file_for_#{source}"
  send(meth) if respond_to?(meth, true)
end

def load_yardoc_from_disk

Raises:
  • (LibraryNotPreparedError) - if the yardoc file has not been 
def load_yardoc_from_disk
  return if ready?
  @@chdir_mutex.synchronize do
    Dir.chdir(source_path_for_disk) do
      Thread.new do
        CLI::Yardoc.run('--no-stats', '-n', '-b', yardoc_file)
      end
    end
  end
  raise LibraryNotPreparedError
end

def load_yardoc_from_gem

Raises:
  • (LibraryNotPreparedError) - if the gem does not have an existing 
def load_yardoc_from_gem
  return if ready?
  ver = version ? "= #{version}" : ">= 0"
  @@chdir_mutex.synchronize do
    Thread.new do
      # Build gem docs on demand
      log.debug "Building gem docs for #{to_s(false)}"
      CLI::Gems.run(name, ver)
      log.debug "Done building gem docs for #{to_s(false)}"
    end
  end
  raise LibraryNotPreparedError
end

def prepare!

Raises:
  • (LibraryNotPreparedError) - if the library is not ready to be

Other tags:
    Note: - You should not directly override this method. Instead, implement 
def prepare!
  return if ready?
  meth = "load_yardoc_from_#{source}"
  send(meth) if respond_to?(meth, true)
end

def ready?

Returns:
  • (Boolean) - whether the library has been completely processed 
def ready?
  return false if yardoc_file.nil?
  serializer.complete?
end

def serializer 

def serializer
  return if yardoc_file.nil?
  Serializers::YardocSerializer.new(yardoc_file)
end

def source_path

Other tags:
    See: LibraryVersion - LibraryVersion documentation for "Implementing a Custom Library Source"

Returns:
  • (nil) - if there is no source code
  • (String) - the location of the source code for a library. This 
def source_path
  @source_path ||= load_source_path
end

def source_path_for_disk

Returns:
  • (String) - the source path for a disk source 
def source_path_for_disk
  File.dirname(yardoc_file) if yardoc_file
end

def source_path_for_gem

Returns:
  • (String) - the source path for a gem source 
def source_path_for_gem
  gemspec.full_gem_path if gemspec
end

def to_s(url_format = true)

Returns:
  • (String) - the string representation of the library.

Parameters:
  • url_format (Boolean) -- if true, returns the string in a URI-compatible 
def to_s(url_format = true)
  version ? "#{name}#{url_format ? '/' : '-'}#{version}" : name.to_s
end

def yardoc_file

Other tags:
    Note: - To implement a custom yardoc file getter, implement

Returns:
  • (nil) - if no yardoc file exists yet. In this case, {#prepare!} will
  • (String) - the location of the yardoc file used to load the object 
def yardoc_file
  @yardoc_file ||= load_yardoc_file
end

def yardoc_file_for_gem

Returns:
  • (String) - the yardoc file for a gem source 
def yardoc_file_for_gem
  require 'rubygems'
  ver = version ? "= #{version}" : ">= 0"
  Registry.yardoc_file_for_gem(name, ver)
end