From 94b75aa3cc98470e680bffd5a54bd392cd25d7ff Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Sun, 30 Aug 2020 08:52:17 -0400 Subject: [PATCH 1/5] 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 --- BUILDING.md | 39 ++++++++++++++++++++++++--------------- Makefile | 3 +-- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 779313e5669820..89cdf0da1eb04c 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -417,41 +417,50 @@ 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 +after `make doc` is finished: -```console -$ make docopen +```bash +make docserve +``` + +This will provide a URL to where you may browse the documentation locally. + +If you prefer to read the documentation as a one-page version of all the +browsable HTML documents, run the following after `make doc` is finished: + +```bash +make docopen ``` This will open a browser with the documentation. 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 5120d517de9759..6341287c37b12e 100644 --- a/Makefile +++ b/Makefile @@ -776,8 +776,7 @@ docopen: $(apidocs_html) .PHONY: docserve docserve: $(apidocs_html) - @$(PYTHON) -mwebbrowser http://localhost:8000/all.html - @$(PYTHON) -m http.server -d $(PWD)/out/doc/api + @$(PYTHON) -m http.server 8000 --bind 127.0.0.1 --directory out/doc/api .PHONY: docclean docclean: From 6add9cf7f0bdb5020e7719def62799a9257c88a2 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Mon, 31 Aug 2020 16:21:12 -0400 Subject: [PATCH 2/5] fixup! doc: spruce up user journey to local docs browsing --- BUILDING.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 89cdf0da1eb04c..aed69e4d731177 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -433,23 +433,24 @@ To read the man page: man doc/node.1 ``` -If you prefer to read the full 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. ```bash make docserve ``` -This will provide a URL to where you may browse the documentation locally. +This will build the docs, spin up a static file server, and provide a URL to +where you may browse the documentation locally. -If you prefer to read the documentation as a one-page version of all the -browsable HTML documents, run the following after `make doc` is finished: +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 browser with the documentation. +This will build the docs, spin up a static file server, and open a URL to a +one-page version of all the browsable HTML documents using the default browser. To test if Node.js was built correctly: From 0a970077c602630dddc913f2571150d3ebede426 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Mon, 31 Aug 2020 19:00:49 -0400 Subject: [PATCH 3/5] fixup! doc: spruce up user journey to local docs browsing --- BUILDING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index aed69e4d731177..89fe9925195f1f 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -439,8 +439,8 @@ If you prefer to read the full documentation in a browser, run the following. make docserve ``` -This will build the docs, spin up a static file server, and provide a URL to -where you may browse the documentation locally. +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. @@ -449,8 +449,8 @@ system has associated with the default web browser, run the following. make docopen ``` -This will build the docs, spin up a static file server, and open a URL to a -one-page version of all the browsable HTML documents using the default browser. +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: From 15014aa301d6409d2c2dac18b93706332c515e84 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Mon, 31 Aug 2020 19:09:21 -0400 Subject: [PATCH 4/5] fixup! doc: spruce up user journey to local docs browsing --- BUILDING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 89fe9925195f1f..119203ff787c2e 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -439,8 +439,8 @@ If you prefer to read the full documentation in a browser, run the following. make docserve ``` -This will spin up a static file server, and provide a URL to where you may -browse the documentation locally. +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. From 515b05f4d2f94ff6ce2e3ee6e2e131161cfd8522 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Fri, 4 Sep 2020 19:48:24 -0400 Subject: [PATCH 5/5] Update Makefile Co-authored-by: Antoine du Hamel --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 6341287c37b12e..eeeafab7d08951 100644 --- a/Makefile +++ b/Makefile @@ -775,7 +775,7 @@ docopen: $(apidocs_html) @$(PYTHON) -mwebbrowser file://$(PWD)/out/doc/api/all.html .PHONY: docserve -docserve: $(apidocs_html) +docserve: $(apidocs_html) $(apiassets) @$(PYTHON) -m http.server 8000 --bind 127.0.0.1 --directory out/doc/api .PHONY: docclean