Add server mode with live reload (rdoc --server)

Implement `rdoc --server[=PORT]` for previewing documentation with
automatic browser refresh on source file changes. The server parses
all sources on startup, serves pages from memory via the Aliki
generator, and watches for file modifications, additions, and
deletions — re-parsing only what changed.

- Move RDoc::Servlet → RDoc::RI::Servlet (clarify RI-specific usage)
- Add --server[=PORT] CLI option (default port 4000)
- Create RDoc::Server WEBrick servlet with:
  - In-memory HTML page cache and search index cache
  - Live-reload via polling script injected into pages
  - Background file watcher (1s mtime polling)
  - Incremental re-parse of changed files only
  - Detection of new and deleted source files
- Add RDoc::Store#remove_file for cleaning up deleted files
- Extract Darkfish#refresh_store_data for server-mode reuse
- Add `rdoc:server` Rake task

Author: st0012

lib/rdoc.rb

@@ -160,7 +160,7 @@ def self.home
   autoload :Generator,      "#{__dir__}/rdoc/generator"
   autoload :Options,        "#{__dir__}/rdoc/options"
   autoload :Parser,         "#{__dir__}/rdoc/parser"
-  autoload :Servlet,        "#{__dir__}/rdoc/servlet"
+  autoload :Server,         "#{__dir__}/rdoc/server"
   autoload :RI,             "#{__dir__}/rdoc/ri"
   autoload :Stats,          "#{__dir__}/rdoc/stats"
   autoload :Store,          "#{__dir__}/rdoc/store"

lib/rdoc/generator/darkfish.rb

@@ -580,6 +580,15 @@ def setup
 
     return unless @store
 
+    refresh_store_data
+  end
+
+  ##
+  # Refreshes the generator's data from the store.  Called by #setup and
+  # can be called again after the store has been updated (e.g. in server
+  # mode after re-parsing changed files).
+
+  def refresh_store_data
     @classes = @store.all_classes_and_modules.sort
     @files   = @store.all_files.sort
     @methods = @classes.flat_map { |m| m.method_list }.sort

lib/rdoc/options.rb

@@ -95,6 +95,7 @@ class RDoc::Options
     pipe
     rdoc_include
     root
+    server_port
     static_path
     template
     template_dir
@@ -328,6 +329,13 @@ class RDoc::Options
 
   attr_reader :visibility
 
+  ##
+  # When set to a port number, starts a live-reloading server instead of
+  # writing files.  Defaults to +false+ (no server).  Set via
+  # <tt>--server[=PORT]</tt>.
+
+  attr_reader :server_port
+
   ##
   # Indicates if files of test suites should be skipped
   attr_accessor :skip_tests
@@ -410,6 +418,7 @@ def init_ivars # :nodoc:
     @output_decoration = true
     @rdoc_include = []
     @root = Pathname(Dir.pwd)
+    @server_port = false
     @show_hash = false
     @static_path = []
     @tab_width = 8
@@ -1123,6 +1132,15 @@ def parse(argv)
       opt.separator "Generic options:"
       opt.separator nil
 
+      opt.on("--server[=PORT]", Integer,
+             "Start a web server to preview",
+             "documentation with live reload.",
+             "Defaults to port 4000.") do |port|
+        @server_port = port || 4000
+      end
+
+      opt.separator nil
+
       opt.on("--write-options",
              "Write .rdoc_options to the current",
              "directory with the given options.  Not all",

lib/rdoc/rdoc.rb

@@ -456,6 +456,19 @@ def document(options)
       exit
     end
 
+    if @options.server_port
+      @store.load_cache
+
+      file_info = parse_files @options.files
+
+      @options.default_title = "RDoc Documentation"
+
+      @store.complete @options.visibility
+
+      start_server
+      return
+    end
+
     unless @options.coverage_report then
       @last_modified = setup_output_dir @options.op_dir, @options.force_update
     end
@@ -516,6 +529,31 @@ def generate
     end
   end
 
+  ##
+  # Starts a live-reloading WEBrick server for previewing documentation.
+  # Called from #document when <tt>--server</tt> is given.
+
+  def start_server
+    require 'webrick'
+
+    port = @options.server_port
+    server = WEBrick::HTTPServer.new(
+      Port: port,
+      Logger: WEBrick::Log.new($stderr, WEBrick::Log::INFO),
+      AccessLog: []
+    )
+    server.mount '/', RDoc::Server, self
+
+    url = "http://localhost:#{port}"
+    $stderr.puts "\nServing documentation at: \e]8;;#{url}\e\\#{url}\e]8;;\e\\"
+    $stderr.puts "Press Ctrl+C to stop."
+
+    trap('INT')  { server.shutdown }
+    trap('TERM') { server.shutdown }
+
+    server.start
+  end
+
   ##
   # Removes a siginfo handler and replaces the previous
 

lib/rdoc/ri.rb

@@ -13,8 +13,9 @@ module RDoc::RI
 
   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

lib/rdoc/ri/driver.rb

@@ -1521,7 +1521,7 @@ def start_server
 
     extra_doc_dirs = @stores.map {|s| s.type == :extra ? s.path : nil}.compact
 
-    server.mount '/', RDoc::Servlet, nil, extra_doc_dirs
+    server.mount '/', RDoc::RI::Servlet, nil, extra_doc_dirs
 
     trap 'INT'  do server.shutdown end
     trap 'TERM' do server.shutdown end

lib/rdoc/servlet.rb lib/rdoc/ri/servlet.rblib/rdoc/servlet.rb renamed to lib/rdoc/ri/servlet.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-require_relative '../rdoc'
+require_relative '../../rdoc'
 require 'erb'
 require 'time'
 require 'json'
@@ -31,7 +31,7 @@
 #
 #   server.mount '/rdoc', RDoc::Servlet, '/rdoc'
 
-class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
+class RDoc::RI::Servlet < WEBrick::HTTPServlet::AbstractServlet
 
   @server_stores = Hash.new { |hash, server| hash[server] = {} }
   @cache         = Hash.new { |hash, store|  hash[store]  = {} }