class YARD::CLI::Server

A local documentation server @since 0.6.0

Attributes

adapter[RW]

@return [Adapter] the adapter to use for loading the web server

libraries[RW]

@return [Hash] a list of library names and yardoc files to serve

options[RW]

@return [Hash] a list of options to pass to the doc server

scripts[RW]

@return [Array<String>] a list of scripts to load @since 0.6.2

server_options[RW]

@return [Hash] a list of options to pass to the web server

template_paths[RW]

@return [Array<String>] a list of template paths to register @since 0.6.2

Public Class Methods

new() click to toggle source

Creates a new instance of the Server command line utility

Calls superclass method
# File lib/yard/cli/server.rb, line 27
def initialize
  super
  self.scripts = []
  self.template_paths = []
  self.libraries = {}
  self.options = SymbolHash.new(false).update(
    :single_library => true,
    :caching => false
  )
  self.server_options = {:Port => 8808}
end

Public Instance Methods

description() click to toggle source
# File lib/yard/cli/server.rb, line 39
def description
  "Runs a local documentation server"
end
run(*args) click to toggle source
# File lib/yard/cli/server.rb, line 43
def run(*args)
  optparse(*args)

  select_adapter.setup
  load_scripts
  load_template_paths
  adapter.new(libraries, options, server_options).start
end

Private Instance Methods

add_gems() click to toggle source
# File lib/yard/cli/server.rb, line 126
def add_gems
  require 'rubygems'
  Gem.source_index.find_name('').each do |spec|
    libraries[spec.name] ||= []
    libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
  end
end
add_gems_from_gemfile(gemfile = nil) click to toggle source
# File lib/yard/cli/server.rb, line 134
def add_gems_from_gemfile(gemfile = nil)
  require 'bundler'
  gemfile ||= "Gemfile"
  if File.exist?("#{gemfile}.lock")
    Bundler::LockfileParser.new(File.read("#{gemfile}.lock")).specs.each do |spec|
      libraries[spec.name] ||= []
      libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s, nil, :gem)]
    end
  else
    log.warn "Cannot find #{gemfile}.lock, ignoring --gemfile option"
  end
rescue LoadError
  log.error "Bundler not available, ignoring --gemfile option"
end
add_libraries(args) click to toggle source
# File lib/yard/cli/server.rb, line 72
def add_libraries(args)
  (0...args.size).step(2) do |index|
    library, dir = args[index], args[index + 1]

    libver = nil
    if dir
      if File.exist?(dir)
        # Provided dir contains a .yardopts file
        libver = create_library_version_if_yardopts_exist(library, dir)
        libver ||= YARD::Server::LibraryVersion.new(library, nil, dir)
      end
    else
      # Check if this dir contains a .yardopts file
      pwd = Dir.pwd
      libver = create_library_version_if_yardopts_exist(library, pwd)

      # Check default location
      yfile = File.join(pwd, '.yardoc')
      libver ||= YARD::Server::LibraryVersion.new(library, nil, yfile)
    end

    # Register library
    if libver
      libver.yardoc_file = File.expand_path(libver.yardoc_file) if libver.yardoc_file
      libver.source_path = File.expand_path(libver.source_path) if libver.source_path
      libraries[library] ||= []
      libraries[library] |= [libver]
    else
      log.warn "Cannot find yardoc db for #{library}: #{dir.inspect}"
    end
  end
end
create_library_version_if_yardopts_exist(library, dir) click to toggle source

@param [String] library The library name. @param [String, nil] dir The argument provided on the CLI after the

library name. Is supposed to point to either a project directory
with a Yard options file, or a yardoc db.

@return [LibraryVersion, nil]

# File lib/yard/cli/server.rb, line 110
def create_library_version_if_yardopts_exist(library, dir)
  if dir
   options_file = File.join(dir, Yardoc::DEFAULT_YARDOPTS_FILE)
   if File.exist?(options_file)
     # Found yardopts, extract db path
     yfile = extract_db_from_options_file(options_file)
     db = File.expand_path(yfile, dir)

     # Create libver
     libver = YARD::Server::LibraryVersion.new(library, nil, db)
     libver.source_path = dir
     libver
   end
  end
end
extract_db_from_options_file(options_file) click to toggle source
# File lib/yard/cli/server.rb, line 236
def extract_db_from_options_file(options_file)
  args = File.read_binary(options_file).shell_split
  db = YARD::Registry.yardoc_file
  opts = OptionParser.new
  opts.on('-b', '--db FILE') {|file| db = file }

  begin
    opts.parse!(args)
  rescue OptionParser::ParseError
    args.shift if args.first && args.first[0,1] != '-'
    retry
  end

  db
end
generate_doc_for_first_time(libver) click to toggle source
# File lib/yard/cli/server.rb, line 226
def generate_doc_for_first_time(libver)
  log.enter_level(Logger::INFO) do
    yardoc_file = libver.yardoc_file.sub /^#{Regexp.quote Dir.pwd}[\\/]+/, ''
    log.info "No yardoc db found in #{yardoc_file}, parsing source before starting server..."
  end
  Dir.chdir(libver.source_path) do
    Yardoc.run('-n')
  end
end
load_scripts() click to toggle source
# File lib/yard/cli/server.rb, line 54
def load_scripts
  scripts.each {|file| load_script(file) }
end
load_template_paths() click to toggle source
# File lib/yard/cli/server.rb, line 58
def load_template_paths
  return if YARD::Config.options[:safe_mode]
  Templates::Engine.template_paths |= template_paths
end
optparse(*args) click to toggle source
# File lib/yard/cli/server.rb, line 149
def optparse(*args)
  opts = OptionParser.new
  opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
  opts.separator ''
  opts.separator 'Example: yard server -m yard .yardoc ruby-core ../ruby/.yardoc'
  opts.separator 'The above example serves documentation for YARD and Ruby-core'
  opts.separator ''
  opts.separator 'If no library/yardoc_file is specified, the server uses'
  opts.separator 'the name of the current directory and `.yardoc` respectively'
  opts.separator ''
  opts.separator "General Options:"
  opts.on('-m', '--multi-library', 'Serves documentation for multiple libraries') do
    options[:single_library] = false
  end
  opts.on('-c', '--cache', 'Caches all documentation to document root (see --docroot)') do
    options[:caching] = true
  end
  opts.on('-r', '--reload', 'Reparses the library code on each request') do
    options[:incremental] = true
  end
  opts.on('-g', '--gems', 'Serves documentation for installed gems') do
    add_gems
  end
  opts.on('-G', '--gemfile [GEMFILE]', 'Serves documentation for gems from Gemfile') do |gemfile|
    add_gems_from_gemfile(gemfile)
  end
  opts.on('-t', '--template-path PATH',
          'The template path to look for templates in. (used with -t).') do |path|
    self.template_paths << path
  end
  opts.separator ''
  opts.separator "Web Server Options:"
  opts.on('-d', '--daemon', 'Daemonizes the server process') do
    server_options[:daemonize] = true
  end
  opts.on('-B HOST', '--bind', 'The host address to bind to') do |host|
    server_options[:Host] = host.to_s
  end        
  opts.on('-p PORT', '--port', 'Serves documentation on PORT') do |port|
    server_options[:Port] = port.to_i
  end
  opts.on('--docroot DOCROOT', 'Uses DOCROOT as document root') do |docroot|
    server_options[:DocumentRoot] = File.expand_path(docroot)
  end
  opts.on('-a', '--adapter ADAPTER', 'Use the ADAPTER (full Ruby class) for web server') do |adapter|
    if adapter.downcase == 'webrick'
      self.adapter = YARD::Server::WebrickAdapter
    elsif adapter.downcase == 'rack'
      self.adapter = YARD::Server::RackAdapter
    else
      self.adapter = eval(adapter)
    end
  end
  opts.on('-s', '--server TYPE', 'Use a specific server type eg. thin,mongrel,cgi (Rack specific)') do |type|
    server_options[:server] = type
  end
  common_options(opts)
  opts.on('-e', '--load FILE', 'A Ruby script to load before the source tree is parsed.') do |file|
    self.scripts << file
  end
  parse_options(opts, args)

  if args.empty? && libraries.empty?
    # No args - try to use current dir
    add_libraries([File.basename(Dir.pwd), nil])

    # Generate doc for first time
    libver = libraries.empty? ? nil : libraries.values.first.first
    if libver and !File.exist?(libver.yardoc_file)
      generate_doc_for_first_time(libver)
    end
  else
    add_libraries(args)
    options[:single_library] = false if libraries.size > 1
  end
end
select_adapter() click to toggle source
# File lib/yard/cli/server.rb, line 63
def select_adapter
  return adapter if adapter
  require 'rubygems'
  require 'rack'
  self.adapter = YARD::Server::RackAdapter
rescue LoadError
  self.adapter = YARD::Server::WebrickAdapter
end