Class: RDoc::RI::Servlet

Inherits:
WEBrick::HTTPServlet::AbstractServlet
  • Object
show all
Defined in:
lib/rdoc/ri/servlet.rb

Overview

This is a WEBrick servlet that allows you to browse ri documentation.

You can show documentation through either ri --server or, with RubyGems 2.0 or newer, gem server. For ri, the server runs on port 8214 by default. For RubyGems the server runs on port 8808 by default.

You can use this servlet in your own project by mounting it on a WEBrick server:

require 'webrick'

server = WEBrick::HTTPServer.new Port: 8000

server.mount '/', RDoc::RI::Servlet

If you want to mount the servlet some other place than the root, provide the base path when mounting:

server.mount '/rdoc', RDoc::RI::Servlet, '/rdoc'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(server, stores, cache, mount_path = nil, extra_doc_dirs = []) ⇒ Servlet

Creates a new WEBrick servlet.

Use mount_path when mounting the servlet somewhere other than /.

Use extra_doc_dirs for additional documentation directories.

server is provided automatically by WEBrick when mounting. stores and cache are provided automatically by the servlet.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/rdoc/ri/servlet.rb', line 71

def initialize(server, stores, cache, mount_path = nil, extra_doc_dirs = [])
  super server

  @cache      = cache
  @mount_path = mount_path
  @extra_doc_dirs = extra_doc_dirs
  @stores     = stores

  @options = Options.new
  @options.op_dir = '.'

  darkfish_dir = nil

  # HACK dup
  $LOAD_PATH.each do |path|
    darkfish_dir = File.join path, 'rdoc/generator/template/darkfish/'
    next unless File.directory? darkfish_dir
    @options.template_dir = darkfish_dir
    break
  end

  @asset_dirs = {
    :darkfish   => darkfish_dir,
    :json_index =>
      File.expand_path('../generator/template/json_index/', __FILE__),
  }
end

Instance Attribute Details

#asset_dirs ⇒ Object (readonly)

Maps an asset type to its path on the filesystem



44
45
46
 
# File 'lib/rdoc/ri/servlet.rb', line 44

def asset_dirs
  @asset_dirs
end

#options ⇒ Object (readonly)

An RDoc::Options instance used for rendering options



49
50
51
 
# File 'lib/rdoc/ri/servlet.rb', line 49

def options
  @options
end

Class Method Details

.get_instance(server, *options) ⇒ Object

Creates an instance of this servlet that shares cached data between requests.



55
56
57
58
59
 
# File 'lib/rdoc/ri/servlet.rb', line 55

def self.get_instance(server, *options) # :nodoc:
  stores = @server_stores[server]

  new server, stores, @cache, *options
end

Instance Method Details

#asset(generator_name, req, res) ⇒ Object

Serves the asset at the path in req for generator_name via res.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/rdoc/ri/servlet.rb', line 102

def asset(generator_name, req, res)
  asset_dir = @asset_dirs[generator_name]

  asset_path = File.join asset_dir, req.path

  if_modified_since req, res, asset_path

  res.body = File.read asset_path

  res.content_type = case req.path
                     when /\.css\z/ then 'text/css'
                     when /\.js\z/  then 'application/javascript'
                     else                'application/octet-stream'
                     end
end

#do_GET(req, res) ⇒ Object

GET request entry point. Fills in res for the path, etc. in req.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/rdoc/ri/servlet.rb', line 121

def do_GET(req, res)
  req.path.sub!(/\A#{Regexp.escape @mount_path}/, '') if @mount_path

  case req.path
  when '/'
    root req, res
  when '/js/darkfish.js', '/js/jquery.js', '/js/search.js',
       %r%^/css/%, %r%^/images/%, %r%^/fonts/%
    asset :darkfish, req, res
  when '/js/navigation.js', '/js/searcher.js'
    asset :json_index, req, res
  when '/js/search_index.js'
    root_search req, res
  else
    show_documentation req, res
  end
rescue WEBrick::HTTPStatus::NotFound => e
  generator = generator_for ::RDoc::Store.new(@options)

  not_found generator, req, res, e.message
rescue WEBrick::HTTPStatus::Status
  raise
rescue => e
  error e, req, res
end

#documentation_page(store, generator, path, req, res) ⇒ Object

Fills in res with the class, module or page for req from store.

path is relative to the mount_path and is used to determine the class, module or page name (/RDoc/Servlet.html becomes RDoc::Servlet). generator is used to create the page.



154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/rdoc/ri/servlet.rb', line 154

def documentation_page(store, generator, path, req, res)
  text_name = path.chomp '.html'
  name = text_name.gsub '/', '::'

  if klass = store.find_class_or_module(name)
    res.body = generator.generate_class klass
  elsif page = store.find_text_page(name.sub(/_([^_]*)\z/, '.\1'))
    res.body = generator.generate_page page
  elsif page = store.find_text_page(text_name.sub(/_([^_]*)\z/, '.\1'))
    res.body = generator.generate_page page
  else
    not_found generator, req, res
  end
end

#documentation_search(store, generator, req, res) ⇒ Object

Creates the JSON search index on res for the given store. generator must respond to #json_index to build. req is ignored.



173
174
175
176
177
178
179
180
181
 
# File 'lib/rdoc/ri/servlet.rb', line 173

def documentation_search(store, generator, req, res)
  json_index = @cache[store].fetch :json_index do
    @cache[store][:json_index] =
      JSON.dump generator.json_index.build_index
  end

  res.content_type = 'application/javascript'
  res.body = "var search_data = #{json_index}"
end

#documentation_source(path) ⇒ Object

Returns the RDoc::Store and path relative to mount_path for documentation at path.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/rdoc/ri/servlet.rb', line 187

def documentation_source(path)
  _, source_name, path = path.split '/', 3

  store = @stores[source_name]
  return store, path if store

  store = store_for source_name

  store.load_all

  @stores[source_name] = store

  return store, path
end

#error(exception, req, res) ⇒ Object

Generates an error page for the exception while handling req on res.



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/rdoc/ri/servlet.rb', line 205

def error(exception, req, res)
  backtrace = exception.backtrace.join "\n"

  res.content_type = 'text/html'
  res.status = 500
  res.body = <<-BODY
<!DOCTYPE html>
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">

<title>Error - #{ERB::Util.html_escape exception.class}</title>

<link type="text/css" media="screen" href="#{@mount_path}/css/rdoc.css" rel="stylesheet">
</head>
<body>
<h1>Error</h1>

<p>While processing <code>#{ERB::Util.html_escape req.request_uri}</code> the
RDoc (#{ERB::Util.html_escape(VERSION)}) server has encountered a
<code>#{ERB::Util.html_escape exception.class}</code>
exception:

<pre>#{ERB::Util.html_escape exception.message}</pre>

<p>Please report this to the
<a href="https://github.com/ruby/rdoc/issues">RDoc issues tracker</a>.  Please
include the RDoc version, the URI above and exception class, message and
backtrace.  If you're viewing a gem's documentation, include the gem name and
version.  If you're viewing Ruby's documentation, include the version of ruby.

<p>Backtrace:

<pre>#{ERB::Util.html_escape backtrace}</pre>

</body>
</html>
    BODY
end

#generator_for(store) ⇒ Object

Instantiates a Darkfish generator for store



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/rdoc/ri/servlet.rb', line 248

def generator_for(store)
  generator = Generator::Darkfish.new store, @options
  generator.file_output = false
  generator.asset_rel_path = '..'
  generator.setup

  rdoc = RDoc.new
  rdoc.store     = store
  rdoc.generator = generator
  rdoc.options   = @options

  @options.main_page = store.main
  @options.title     = store.title

  generator
end

#if_modified_since(req, res, path = nil) ⇒ Object

Handles the If-Modified-Since HTTP header on req for path. If the file has not been modified a Not Modified response is returned. If the file has been modified a Last-Modified header is added to res.



270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/rdoc/ri/servlet.rb', line 270

def if_modified_since(req, res, path = nil)
  last_modified = File.stat(path).mtime if path

  res['last-modified'] = last_modified.httpdate

  return unless ims = req['if-modified-since']

  ims = Time.parse ims

  unless ims < last_modified
    res.body = ''
    raise WEBrick::HTTPStatus::NotModified
  end
end

#installed_docs ⇒ Object

Returns an Array of installed documentation.

Each entry contains the documentation name (gem name, 'Ruby Documentation', etc.), the path relative to the mount point, whether the documentation exists, the type of documentation (See RDoc::RI::Paths#each) and the filesystem to the RDoc::Store for the documentation.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/rdoc/ri/servlet.rb', line 293

def installed_docs
  extra_counter = 0
  ri_paths.map do |path, type|
    store = ::RDoc::Store.new(@options, path: path, type: type)
    exists = File.exist? store.cache_path

    case type
    when :gem
      gem_path = path[%r%/([^/]*)/ri$%, 1]
      [gem_path, "#{gem_path}/", exists, type, path]
    when :system
      ['Ruby Documentation', 'ruby/', exists, type, path]
    when :site
      ['Site Documentation', 'site/', exists, type, path]
    when :home
      ['Home Documentation', 'home/', exists, type, path]
    when :extra
      extra_counter += 1
      store.load_cache if exists
      title = store.title || "Extra Documentation"
      [title, "extra-#{extra_counter}/", exists, type, path]
    end
  end
end

#not_found(generator, req, res, message = nil) ⇒ Object

Returns a 404 page built by generator for req on res.



321
322
323
324
325
 
# File 'lib/rdoc/ri/servlet.rb', line 321

def not_found(generator, req, res, message = nil)
  message ||= "The page <kbd>#{ERB::Util.h req.path}</kbd> was not found"
  res.body = generator.generate_servlet_not_found message
  res.status = 404
end

#ri_paths(&block) ⇒ Object

Enumerates the ri paths. See RDoc::RI::Paths#each



330
331
332
 
# File 'lib/rdoc/ri/servlet.rb', line 330

def ri_paths(&block)
  RI::Paths.each true, true, true, :all, *@extra_doc_dirs, &block #TODO: pass extra_dirs
end

#root(req, res) ⇒ Object

Generates the root page on res. req is ignored.



337
338
339
340
341
342
343
 
# File 'lib/rdoc/ri/servlet.rb', line 337

def root(req, res)
  generator = Generator::Darkfish.new nil, @options

  res.body = generator.generate_servlet_root installed_docs

  res.content_type = 'text/html'
end

#root_search(req, res) ⇒ Object

Generates a search index for the root page on res. req is ignored.



348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/rdoc/ri/servlet.rb', line 348

def root_search(req, res)
  search_index = []
  info         = []

  installed_docs.map do |name, href, exists, type, path|
    next unless exists

    search_index << name

    case type
    when :gem
      gemspec = path.gsub(%r%/doc/([^/]*?)/ri$%,
                          '/specifications/\1.gemspec')

      spec = Gem::Specification.load gemspec

      path    = spec.full_name
      comment = spec.summary
    when :system
      path    = 'ruby'
      comment = 'Documentation for the Ruby standard library'
    when :site
      path    = 'site'
      comment = 'Documentation for non-gem libraries'
    when :home
      path    = 'home'
      comment = 'Documentation from your home directory'
    when :extra
      comment = name
    end

    info << [name, '', path, '', comment]
  end

  index = {
    :index => {
      :searchIndex     => search_index,
      :longSearchIndex => search_index,
      :info            => info,
    }
  }

  res.body = "var search_data = #{JSON.dump index};"
  res.content_type = 'application/javascript'
end

#show_documentation(req, res) ⇒ Object

Displays documentation for req on res, whether that be HTML or some asset.



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/rdoc/ri/servlet.rb', line 398

def show_documentation(req, res)
  store, path = documentation_source req.path

  if_modified_since req, res, store.cache_path

  generator = generator_for store

  case path
  when nil, '', 'index.html'
    res.body = generator.generate_index
  when 'table_of_contents.html'
    res.body = generator.generate_table_of_contents
  when 'js/search_index.js'
    documentation_search store, generator, req, res
  else
    documentation_page store, generator, path, req, res
  end
ensure
  res.content_type ||= 'text/html'
end

#store_for(source_name) ⇒ Object

Returns an RDoc::Store for the given source_name ('ruby' or a gem name).



422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/rdoc/ri/servlet.rb', line 422

def store_for(source_name)
  case source_name
  when 'home'
    ::RDoc::Store.new(@options, path: RI::Paths.home_dir, type: :home)
  when 'ruby'
    ::RDoc::Store.new(@options, path: RI::Paths.system_dir, type: :system)
  when 'site'
    ::RDoc::Store.new(@options, path: RI::Paths.site_dir, type: :site)
  when /\Aextra-(\d+)\z/
    index = $1.to_i - 1
    ri_dir = installed_docs[index][4]
    ::RDoc::Store.new(@options, path: ri_dir, type: :extra)
  else
    ri_dir, type = ri_paths.find do |dir, dir_type|
      next unless dir_type == :gem

      source_name == dir[%r%/([^/]*)/ri$%, 1]
    end

    raise WEBrick::HTTPStatus::NotFound,
          "Could not find gem \"#{ERB::Util.html_escape(source_name)}\". Are you sure you installed it?" unless ri_dir

    store = ::RDoc::Store.new(@options, path: ri_dir, type: type)

    return store if File.exist? store.cache_path

    raise WEBrick::HTTPStatus::NotFound,
          "Could not find documentation for \"#{ERB::Util.html_escape(source_name)}\". Please run `gem rdoc --ri gem_name`"

  end
end