tools: the `docserve` make target doesn't seem to finally serve

[DerekNonGeneric]

• Version: n/a
• Platform: Debian 10 WSL
• Subsystem: tools

What steps will reproduce the bug?

Simply clone the repo and run make docserve.

How often does it reproduce? Is there a required condition?

Always.

What is the expected behavior?

To actually serve the static documentation pages.

What do you see instead?

Additional information

It's possible that this issue should be in @nodejs/help, but I'm somewhat convinced that this is indeed a bug in the Makefile code since this doesn't work using Python 2.7.16. If it's supposed to be Python 3 code, perhaps we should force that to make this work, but at the same time, I don't understand why the command is so complex. Shouldn't it just be the following?

python -m SimpleHTTPServer 8000

Refs: https://docs.python.org/2/library/simplehttpserver.html

/cc @aduh95 as was the one who introduced this feature in #33221

[aduh95]

For reference, the target code is the following:

node/Makefile

Lines 778 to 780 in c2996ce

	docserve: $(apidocs_html)
	@$(PYTHON) -mwebbrowser http://localhost:8000/all.html
	@$(PYTHON) -m http.server -d $(PWD)/out/doc/api

This is indeed Python 3 only (https://docs.python.org/3/library/http.server.html). I don't know if we want to patch it given the fact that Python 2 has reached End-of-Life and this is not actually part of the build chain anyway.

I don't understand why the command is so complex.

python -m http.server opens a webserver at localhost:8000; -d $(PWD)/out/doc/api sets the document root to the generated doc folder, that option does not exist on Python 2 AFAIK.

Python 2 users can use make docopen instead, maybe that would be enough for you?

[DerekNonGeneric]

I see why this is happening now. I am running Debian 10, so the following line in the Makefile detects python as Python 2.

node/Makefile

Line 4 in a1faa8d

PYTHON ?= python

Here's the reason why…

At any given time, the binary package python3 will represent the current default Debian Python 3 version; the binary package python will represent the current default Debian Python 2 version.
— https://www.debian.org/doc/packaging-manuals/python-policy/ch-python.html

---

For this to work for me, I would need line 4 to be …

PYTHON ?= python3

… to execute the following.

node/Makefile

Lines 778 to 780 in c2996ce

	docserve: $(apidocs_html)
	@$(PYTHON) -mwebbrowser http://localhost:8000/all.html
	@$(PYTHON) -m http.server -d $(PWD)/out/doc/api

However, doing so would likely break all the other commands expecting PYTHON to be the Python 2 binary.

---

We could add a new constant called PYTHON3 like this:

PYTHON3 ?= python3

And update the Makefile to use it for all of the newest targets

---

Python is being used quite heavily in the build tooling, so I wonder what our stance is on this. Here are Debian's goals.

Debian currently supports two Python stacks, one for Python 3 and one for Python 2. The long term goal for Debian is to reduce this to one stack, dropping the Python 2 stack at some time.
— https://www.debian.org/doc/packaging-manuals/python-policy/ch-python3.html

💭 We probably want to ensure everything is working w/ Python 3 in the near-term.

[aduh95]

node/BUILDING.md

Lines 225 to 230 in a1faa8d

	### Note about Python 2 and Python 3
	The Node.js project supports both Python 3 and Python 2 for building.
	If both are installed Python 3 will be used. If only Python 2 is available
	it will be used instead. When possible we recommend that you build and
	test with Python 3.

If you have Python 3 installed but isn't used by the build tools, there is a bug somewhere.

FWIW Python 2 is currently still supported for UNIX/Linux systems only. On Windows, Python 3 is already required according to our docs:

node/BUILDING.md

Lines 523 to 529 in a1faa8d

	### Windows
	#### Prerequisites
	##### Option 1: Manual install
	* [Python 3.8](https://www.python.org/downloads/)

[DerekNonGeneric]

This would technically fall under UNIX prerequisites, but somehow the python command being picked up by the Makefile is the correct version (Python 3). Going to remove my new constant now since it just works™.