rdoc 7.2.0 → 8.1.0

data/lib/rdoc/ri/servlet.rb

@@ -0,0 +1,456 @@
+# frozen_string_literal: true
+require_relative '../../rdoc'
+require 'erb'
+require 'time'
+require 'json'
+
+begin
+  require 'webrick'
+rescue LoadError
+  abort "webrick is not found. You may need to `gem install webrick` to install webrick."
+end
+
+module RDoc
+  module RI
+    ##
+    # 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'
+
+    class Servlet < WEBrick::HTTPServlet::AbstractServlet
+
+      @server_stores = Hash.new { |hash, server| hash[server] = {} }
+      @cache         = Hash.new { |hash, store|  hash[store]  = {} }
+
+      ##
+      # Maps an asset type to its path on the filesystem
+
+      attr_reader :asset_dirs
+
+      ##
+      # An RDoc::Options instance used for rendering options
+
+      attr_reader :options
+
+      ##
+      # Creates an instance of this servlet that shares cached data between
+      # requests.
+
+      def self.get_instance(server, *options) # :nodoc:
+        stores = @server_stores[server]
+
+        new server, stores, @cache, *options
+      end
+
+      ##
+      # 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.
+
+      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
+
+      ##
+      # Serves the asset at the path in +req+ for +generator_name+ via +res+.
+
+      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
+
+      ##
+      # GET request entry point.  Fills in +res+ for the path, etc. in +req+.
+
+      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
+
+      ##
+      # 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.
+
+      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
+
+      ##
+      # Creates the JSON search index on +res+ for the given +store+.  +generator+
+      # must respond to \#json_index to build.  +req+ is ignored.
+
+      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
+
+      ##
+      # Returns the RDoc::Store and path relative to +mount_path+ for
+      # documentation at +path+.
+
+      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
+
+      ##
+      # Generates an error page for the +exception+ while handling +req+ on +res+.
+
+      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
+
+      ##
+      # Instantiates a Darkfish generator for +store+
+
+      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
+
+      ##
+      # 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+.
+
+      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
+
+      ##
+      # 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.
+
+      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
+
+      ##
+      # Returns a 404 page built by +generator+ for +req+ on +res+.
+
+      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
+
+      ##
+      # Enumerates the ri paths.  See RDoc::RI::Paths#each
+
+      def ri_paths(&block)
+        RI::Paths.each true, true, true, :all, *@extra_doc_dirs, &block #TODO: pass extra_dirs
+      end
+
+      ##
+      # Generates the root page on +res+.  +req+ is ignored.
+
+      def root(req, res)
+        generator = Generator::Darkfish.new nil, @options
+
+        res.body = generator.generate_servlet_root installed_docs
+
+        res.content_type = 'text/html'
+      end
+
+      ##
+      # Generates a search index for the root page on +res+.  +req+ is ignored.
+
+      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
+
+      ##
+      # Displays documentation for +req+ on +res+, whether that be HTML or some
+      # asset.
+
+      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
+
+      ##
+      # Returns an RDoc::Store for the given +source_name+ ('ruby' or a gem name).
+
+      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
+
+    end
+  end
+end

data/lib/rdoc/ri/store.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
-module RDoc::RI
+module RDoc
+  module RI
 
-  Store = RDoc::Store # :nodoc:
+    Store = ::RDoc::Store # :nodoc:
 
+  end
 end

data/lib/rdoc/ri/task.rb

@@ -6,66 +6,70 @@ end unless defined?(RDoc)
 
 require_relative '../task'
 
-##
-# RDoc::RI::Task creates ri data in <code>./.rdoc</code> for your project.
-#
-# It contains the following tasks:
-#
-# [ri]
-#   Build ri data
-#
-# [clobber_ri]
-#   Delete ri data files.  This target is automatically added to the main
-#   clobber target.
-#
-# [reri]
-#   Rebuild the ri data from scratch even if they are not out of date.
-#
-# Simple example:
-#
-#   require 'rdoc/ri/task'
-#
-#   RDoc::RI::Task.new do |ri|
-#     ri.main = 'README.md'
-#     ri.rdoc_files.include 'README.md', 'lib/**/*.rb'
-#   end
-#
-# For further configuration details see RDoc::Task.
+module RDoc
+  module RI
+    ##
+    # RDoc::RI::Task creates ri data in <code>./.rdoc</code> for your project.
+    #
+    # It contains the following tasks:
+    #
+    # [ri]
+    #   Build ri data
+    #
+    # [clobber_ri]
+    #   Delete ri data files.  This target is automatically added to the main
+    #   clobber target.
+    #
+    # [reri]
+    #   Rebuild the ri data from scratch even if they are not out of date.
+    #
+    # Simple example:
+    #
+    #   require 'rdoc/ri/task'
+    #
+    #   RDoc::RI::Task.new do |ri|
+    #     ri.main = 'README.md'
+    #     ri.rdoc_files.include 'README.md', 'lib/**/*.rb'
+    #   end
+    #
+    # For further configuration details see RDoc::Task.
 
-class RDoc::RI::Task < RDoc::Task
+    class Task < ::RDoc::Task
 
-  DEFAULT_NAMES = { # :nodoc:
-    :clobber_rdoc => :clobber_ri,
-    :rdoc         => :ri,
-    :rerdoc       => :reri,
-  }
+      DEFAULT_NAMES = { # :nodoc:
+        :clobber_rdoc => :clobber_ri,
+        :rdoc         => :ri,
+        :rerdoc       => :reri,
+      }
 
-  ##
-  # Create an ri task with the given name. See RDoc::Task for documentation on
-  # setting names.
+      ##
+      # Create an ri task with the given name. See RDoc::Task for documentation on
+      # setting names.
 
-  def initialize(name = DEFAULT_NAMES) # :yield: self
-    super
-  end
+      def initialize(name = DEFAULT_NAMES) # :yield: self
+        super
+      end
 
-  def clobber_task_description # :nodoc:
-    "Remove RI data files"
-  end
+      def clobber_task_description # :nodoc:
+        "Remove RI data files"
+      end
 
-  ##
-  # Sets default task values
+      ##
+      # Sets default task values
 
-  def defaults
-    super
+      def defaults
+        super
 
-    @rdoc_dir = '.rdoc'
-  end
+        @rdoc_dir = '.rdoc'
+      end
 
-  def rdoc_task_description # :nodoc:
-    'Build RI data files'
-  end
+      def rdoc_task_description # :nodoc:
+        'Build RI data files'
+      end
 
-  def rerdoc_task_description # :nodoc:
-    'Rebuild RI data files'
+      def rerdoc_task_description # :nodoc:
+        'Rebuild RI data files'
+      end
+    end
   end
 end

data/lib/rdoc/ri.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 require_relative '../rdoc'
 
-##
-# Namespace for the ri command line tool's implementation.
-#
-# See <tt>ri --help</tt> for details.
+module RDoc
+  ##
+  # Namespace for the ri command line tool's implementation.
+  #
+  # See <tt>ri --help</tt> for details.
 
-module RDoc::RI
+  module RI
 
-  ##
-  # Base RI error class
+    ##
+    # Base RI error class
 
-  class Error < RDoc::Error; end
+    class Error < ::RDoc::Error; end
 
-  autoload :Driver, "#{__dir__}/ri/driver"
-  autoload :Paths,  "#{__dir__}/ri/paths"
-  autoload :Store,  "#{__dir__}/ri/store"
+    autoload :Driver,  "#{__dir__}/ri/driver"
+    autoload :Paths,   "#{__dir__}/ri/paths"
+    autoload :Servlet, "#{__dir__}/ri/servlet"
+    autoload :Store,   "#{__dir__}/ri/store"
 
+  end
 end