Class: YARD::Server::LibraryVersion

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/server/library_version.rb

Overview

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 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 .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', ...),
             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 “gem” (technically the disk, but a separate type nonetheless). In these two cases, the yardoc file sits somewhere on your filesystem, though it may also be built dynamically if it does not yet exist. This behaviour 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 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 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.

Examples:

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
      # 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)

Since:

  • 0.6.0

Constant Summary collapse

@@chdir_mutex =

Since:

  • 0.6.0

Mutex.new

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, version = nil, yardoc = nil, source = :disk) ⇒ LibraryVersion

Returns a new instance of LibraryVersion.

Parameters:

  • name (String) —

    the name of the library

  • version (String) (defaults to: nil) —

    the specific (usually, but not always, numeric) library version

  • yardoc (String) (defaults to: nil) —

    the location of the yardoc file, or nil if it is generated later

  • source (Symbol) (defaults to: :disk) —

    the location of the files used to build the yardoc. Builtin source types are :disk or :gem.

Since:

  • 0.6.0



121
122
123
124
125
126
127
 
# File 'lib/yard/server/library_version.rb', line 121

def initialize(name, version = nil, yardoc = nil, source = :disk)
  self.name = name
  self.yardoc_file = yardoc
  self.version = version
  self.source = source
  self.source_path = load_source_path
end

Instance Attribute Details

#name ⇒ String

Returns the name of the library.

Returns:

  • (String) —

    the name of the library

Since:

  • 0.6.0



90
91
92
 
# File 'lib/yard/server/library_version.rb', line 90

def name
  @name
end

#source ⇒ Symbol

Returns 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.

Returns:

  • (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 Also:

Since:

  • 0.6.0



106
107
108
 
# File 'lib/yard/server/library_version.rb', line 106

def source
  @source
end

#source_path ⇒ String?

Returns:

  • (String) —

    the location of the source code for a library. This value is filled by calling #source_path_for_SOURCE on this class.

  • (nil) —

    if there is no source code

See Also:

Since:

  • 0.6.0



112
113
114
 
# File 'lib/yard/server/library_version.rb', line 112

def source_path
  @source_path
end

#version ⇒ String

Returns the version of the specific library.

Returns:

  • (String) —

    the version of the specific library

Since:

  • 0.6.0



93
94
95
 
# File 'lib/yard/server/library_version.rb', line 93

def version
  @version
end

#yardoc_file ⇒ String?

Returns:

  • (String) —

    the location of the yardoc file used to load the object information from.

  • (nil) —

    if no yardoc file exists yet. In this case, #prepare! will be called on this library to build the yardoc file.

Since:

  • 0.6.0



99
100
101
 
# File 'lib/yard/server/library_version.rb', line 99

def yardoc_file
  @yardoc_file
end

Instance Method Details

#eql?(other) ⇒ Boolean Also known as: ==, equal?

Returns whether another LibraryVersion is equal to this one.

Returns:

  • (Boolean) —

    whether another LibraryVersion is equal to this one

Since:

  • 0.6.0



141
142
143
144
 
# File 'lib/yard/server/library_version.rb', line 141

def eql?(other)
  other.is_a?(LibraryVersion) && other.name == name &&
    other.version == version && other.yardoc_file == yardoc_file
end

#gemspec ⇒ Gem::Specification?

Returns:

  • (Gem::Specification) —

    a gemspec object for a given library. Used for :gem source types.

  • (nil) —

    if there is no installed gem for the library

Since:

  • 0.6.0



179
180
181
182
 
# File 'lib/yard/server/library_version.rb', line 179

def gemspec
  ver = version ? "= #{version}" : ">= 0"
  Gem.source_index.find_name(name, ver).last
end

#hash ⇒ Fixnum

Returns used for Hash mapping.

Returns:

  • (Fixnum) —

    used for Hash mapping.

Since:

  • 0.6.0



138
 
# File 'lib/yard/server/library_version.rb', line 138

def hash; to_s.hash end

#load_yardoc_from_disk ⇒ Object (protected)

Called when a library of source type “disk” is to be prepared. In this case, the #yardoc_file should already be set, but the library may not be prepared. Run preparation if not done.

Raises:

Since:

  • 0.6.0



194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/yard/server/library_version.rb', line 194

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

#load_yardoc_from_gem ⇒ Object (protected)

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.

Raises:

Since:

  • 0.6.0



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/yard/server/library_version.rb', line 214

def load_yardoc_from_gem
  require 'rubygems'
  ver = version ? "= #{version}" : ">= 0"
  self.yardoc_file = Registry.yardoc_file_for_gem(name, ver)
  return if ready?

  @@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)
      self.yardoc_file = Registry.yardoc_file_for_gem(name, ver)
    end
  end

  raise LibraryNotPreparedError
end

#prepare! ⇒ Object

Note:

You should not directly override this method. Instead, implement load_yardoc_from_SOURCENAME when implementing loading for a specific source type. See the YARD::Server::LibraryVersion documentation for “Implementing a Custom Library Source”

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).

Raises:

  • (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 is not necessary.

Since:

  • 0.6.0



170
171
172
173
174
 
# File 'lib/yard/server/library_version.rb', line 170

def prepare!
  return if ready?
  meth = "load_yardoc_from_#{source}"
  send(meth) if respond_to?(meth, true)
end

#ready? ⇒ Boolean

Returns whether the library has been completely processed and is ready to be served.

Returns:

  • (Boolean) —

    whether the library has been completely processed and is ready to be served

Since:

  • 0.6.0



150
151
152
153
 
# File 'lib/yard/server/library_version.rb', line 150

def ready?
  return false if yardoc_file.nil?
  serializer.complete?
end

#source_path_for_disk ⇒ String (protected)

Returns the source path for a disk source.

Returns:

  • (String) —

    the source path for a disk source

Since:

  • 0.6.0



233
234
235
 
# File 'lib/yard/server/library_version.rb', line 233

def source_path_for_disk
  File.dirname(yardoc_file) if yardoc_file
end

#source_path_for_gem ⇒ String (protected)

Returns the source path for a gem source.

Returns:

  • (String) —

    the source path for a gem source

Since:

  • 0.6.0



238
239
240
 
# File 'lib/yard/server/library_version.rb', line 238

def source_path_for_gem
  gemspec.full_gem_path if gemspec
end

#to_s(url_format = true) ⇒ String

Returns the string representation of the library.

Parameters:

  • url_format (Boolean) (defaults to: true) —

    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.

Returns:

  • (String) —

    the string representation of the library.

Since:

  • 0.6.0



133
134
135
 
# File 'lib/yard/server/library_version.rb', line 133

def to_s(url_format = true)
  version ? "#{name}#{url_format ? '/' : '-'}#{version}" : "#{name}"
end