Add make html-server for live-reloading doc preview

RDoc now has a `--server` mode that starts a local HTTP server
with live reload. Add an `html-server` make target so developers
can preview Ruby documentation while editing source files.

Usage: `make html-server` from the build directory, then visit
http://localhost:4000. Editing any source file's documentation
comment will automatically refresh the browser.

Use `make html-server RDOC_SERVER_PORT=8080` to change the port.

Pin rdoc in `bundled_gems` to the commit that includes server
mode support (e4e332f2).

Author: st0012

common.mk

@@ -77,6 +77,7 @@ INSTALL_DOC_OPTS = --rdoc-output="$(RDOCOUT)" --html-output="$(HTMLOUT)"
 RDOC_GEN_OPTS = --no-force-update \
 	--exclude '^lib/rubygems/core_ext/kernel_require\.rb$$' \
 	$(empty)
+RDOC_SERVER_PORT = 4000
 
 INITOBJS      = dmyext.$(OBJEXT) dmyenc.$(OBJEXT)
 NORMALMAINOBJ = main.$(OBJEXT)
@@ -630,6 +631,10 @@ html: PHONY $(RDOC_DEPENDS) $(RBCONFIG)
 	@echo Generating RDoc HTML files
 	$(Q) $(RDOC) --op "$(HTMLOUT)" $(RDOC_GEN_OPTS) $(RDOCFLAGS) .
 
+html-server: PHONY $(RDOC_DEPENDS) $(RBCONFIG)
+	@echo Starting RDoc server with live reload
+	$(Q) $(RDOC) --server=$(RDOC_SERVER_PORT) $(RDOC_GEN_OPTS) $(RDOCFLAGS) .
+
 RDOC_COVERAGE_EXCLUDES = -x ^ext/json -x ^ext/openssl -x ^ext/psych \
 	-x ^lib/bundler -x ^lib/rubygems \
 	-x ^lib/did_you_mean -x ^lib/error_highlight -x ^lib/syntax_suggest

doc/contributing/documentation_guide.md

@@ -20,12 +20,19 @@ build directory:
 make html
 ```
 
+Or, to start a live-reloading server that automatically refreshes
+the browser when you edit source files:
+
+```sh
+make html-server
+```
+
+Then visit http://localhost:4000 in your browser.
+To use a different port: `make html-server RDOC_SERVER_PORT=8080`.
+
 If you don't have a build directory, follow the [quick start
 guide](building_ruby.md#label-Quick+start+guide) up to step 4.
 
-Then you can preview your changes by opening
-`{build folder}/.ext/html/index.html` file in your browser.
-
 ## Goal
 
 The goal of Ruby documentation is to impart the most important

gems/bundled_gems

@@ -37,7 +37,7 @@ ostruct             0.6.3   https://github.com/ruby/ostruct
 pstore              0.2.1   https://github.com/ruby/pstore
 benchmark           0.5.0   https://github.com/ruby/benchmark
 logger              1.7.0   https://github.com/ruby/logger
-rdoc                7.2.0   https://github.com/ruby/rdoc
+rdoc                7.2.0   https://github.com/ruby/rdoc e4e332f2857f37f04f2f0aa359ce269a2c624176
 win32ole            1.9.3   https://github.com/ruby/win32ole
 irb                 1.17.0  https://github.com/ruby/irb
 reline              0.6.3   https://github.com/ruby/reline