From fb1a1339de36af286b816bc07d3249b9f868bc96 Mon Sep 17 00:00:00 2001
From: Derek Lewis <DerekNonGeneric@inf.is>
Date: Sun, 30 Aug 2020 08:52:17 -0400
Subject: [PATCH] doc: spruce up user journey to local docs browsing

This patch improves the means by which the docs are viewed locally.

* Remove extraneous code in the `docserve` Makefile target
* Document the `docserve` task for all to know
* Bring all code snippets in this section up to speed
* Clarify the purpose of each documentation browsing method

Fixes: https://github.com/nodejs/node/issues/34977

PR-URL: https://github.com/nodejs/node/pull/34986
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
---
 BUILDING.md | 42 ++++++++++++++++++++++++++----------------
 Makefile    |  5 ++---
 2 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/BUILDING.md b/BUILDING.md
index 37b79a02570ed9..85d8d1ffa159ec 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -423,41 +423,51 @@ To build the documentation:
 
 This will build Node.js first (if necessary) and then use it to build the docs:
 
-```console
-$ make doc
+```bash
+make doc
 ```
 
 If you have an existing Node.js build, you can build just the docs with:
 
-```console
-$ NODE=/path/to/node make doc-only
+```bash
+NODE=/path/to/node make doc-only
 ```
 
-To read the documentation:
+To read the man page:
 
-```console
-$ man doc/node.1
+```bash
+man doc/node.1
 ```
 
-If you prefer to read the documentation in a browser,
-run the following after `make doc` is finished:
+If you prefer to read the full documentation in a browser, run the following.
 
-```console
-$ make docopen
+```bash
+make docserve
 ```
 
-This will open a browser with the documentation.
+This will spin up a static file server and provide a URL to where you may browse
+the documentation locally.
+
+If you're comfortable viewing the documentation using the program your operating
+system has associated with the default web browser, run the following.
+
+```bash
+make docopen
+```
+
+This will open a file URL to a one-page version of all the browsable HTML
+documents using the default browser.
 
 To test if Node.js was built correctly:
 
-```console
-$ ./node -e "console.log('Hello from Node.js ' + process.version)"
+```bash
+./node -e "console.log('Hello from Node.js ' + process.version)"
 ```
 
 To install this version of Node.js into a system directory:
 
-```console
-$ [sudo] make install
+```bash
+[sudo] make install
 ```
 
 #### Building a debug build
diff --git a/Makefile b/Makefile
index e01657e8cb2a26..8ffd2c79c9be52 100644
--- a/Makefile
+++ b/Makefile
@@ -771,9 +771,8 @@ docopen: $(apidocs_html)
 	@$(PYTHON) -mwebbrowser file://$(PWD)/out/doc/api/all.html
 
 .PHONY: docserve
-docserve: $(apidocs_html)
-	@$(PYTHON) -mwebbrowser http://localhost:8000/all.html
-	@$(PYTHON) -m http.server -d $(PWD)/out/doc/api
+docserve: $(apidocs_html) $(apiassets)
+	@$(PYTHON) -m http.server 8000 --bind 127.0.0.1 --directory out/doc/api
 
 .PHONY: docclean
 docclean: