build, doc: generate node.1 with doc-kit

Signed-off-by: avivkeller <me@aviv.sh>
PR-URL: https://github.com/nodejs/node/pull/62044
Reviewed-By: Claudio Wunder <cwunder@gnome.org>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

BUILDING.md

@@ -558,7 +558,7 @@ NODE=/path/to/node make doc-only
 To read the man page:
 
 ```bash
-man doc/node.1
+man out/doc/node.1
 ```
 
 If you prefer to read the full documentation in a browser, run the following.

Makefile

@@ -196,7 +196,7 @@ config.gypi: configure configure.py src/node_version.h
 	fi
 
 .PHONY: install
-install: all ## Install node into $PREFIX (default=/usr/local).
+install: all out/doc/node.1 ## Install node into $PREFIX (default=/usr/local).
 	$(PYTHON) tools/install.py $@ --dest-dir '$(DESTDIR)' --prefix '$(PREFIX)'
 
 .PHONY: uninstall
@@ -856,7 +856,7 @@ VERSION=v$(RAWVER)
 
 .PHONY: doc-only
 .NOTPARALLEL: doc-only
-doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json out/doc/llms.txt out/doc/apilinks.json  ## Builds the docs with the local or the global Node.js binary.
+doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/node.1 out/doc/api/all.html out/doc/api/all.json out/doc/llms.txt out/doc/apilinks.json  ## Builds the docs with the local or the global Node.js binary.
 
 .PHONY: doc
 doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary.
@@ -932,6 +932,19 @@ out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc
 		) \
 	fi
 
+out/doc/node.1: doc/api/cli.md tools/doc/node_modules | out/doc
+	@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
+		echo "Skipping $@ (no crypto and/or no ICU)"; \
+	else \
+		$(call available-node, \
+			$(DOC_KIT) generate \
+			-t man-page \
+			-i $< \
+			-o $(@D) \
+			-v $(VERSION) \
+		) \
+	fi
+
 .PHONY: docopen
 docopen: doc-only ## Open the documentation in a web browser.
 	@$(PYTHON) -mwebbrowser file://$(abspath $<)
@@ -1269,7 +1282,7 @@ $(TARBALL): $(TARBALL_DEPS)
 	git checkout-index -a -f --prefix=$(TARNAME)/
 ifneq ($(SKIP_SHARED_DEPS), 1)
 	mkdir -p $(TARNAME)/doc/api
-	cp doc/node.1 $(TARNAME)/doc/node.1
+	cp out/doc/node.1 $(TARNAME)/doc/node.1
 	cp -r out/doc/api/* $(TARNAME)/doc/api/
 endif
 	sed 's/fileset = fileset.intersection (fileset.gitTracked root)/fileset =/' tools/nix/v8.nix > $(TARNAME)/tools/nix/v8.nix 

src/node_options.cc

@@ -461,10 +461,6 @@ void Parse(
     args, exec_args, v8_args, options, required_env_settings, errors);
 }
 
-// XXX: If you add an option here, please also add it to doc/node.1 and
-// doc/api/cli.md
-// TODO(addaleax): Make that unnecessary.
-
 DebugOptionsParser::DebugOptionsParser() {
   AddOption("--inspect-port",
             "set host:port for inspector",

test/doctool/test-manpage-envvars.mjs

@@ -1,9 +1,14 @@
-import '../common/index.mjs';
+import * as common from '../common/index.mjs';
+
 import assert from 'node:assert';
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { resolve, join } from 'node:path';
 
+if (common.isWindows) {
+  common.skip('`make doc` does not run on Windows');
+}
+
 // This test checks that all the environment variables defined in the public CLI documentation (doc/api/cli.md)
 // are also documented in the manpage file (doc/node.1) and vice-versa (that all the environment variables
 // in the manpage are present in the CLI documentation)
@@ -14,11 +19,11 @@ const cliMdEnvVarNames = await collectCliMdEnvVarNames();
 const manpageEnvVarNames = await collectManPageEnvVarNames();
 
 assert(cliMdEnvVarNames.size > 0,
-       'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file'
+       'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file',
 );
 
 assert(manpageEnvVarNames.size > 0,
-       'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file'
+       'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file',
 );
 
 for (const envVarName of cliMdEnvVarNames) {
@@ -35,7 +40,7 @@ if (manpageEnvVarNames.size > 0) {
 }
 
 async function collectManPageEnvVarNames() {
-  const manPagePath = join(rootDir, 'doc', 'node.1');
+  const manPagePath = join(rootDir, 'out', 'doc', 'node.1');
   const fileStream = createReadStream(manPagePath);
 
   const rl = createInterface({

test/doctool/test-manpage-node-options.js

@@ -3,6 +3,10 @@ const common = require('../common');
 if (process.config.variables.node_without_node_options)
   common.skip('missing NODE_OPTIONS support');
 
+if (common.isWindows) {
+  common.skip('`make doc` does not run on Windows');
+}
+
 // Test options specified by env variable.
 
 const assert = require('assert');
@@ -22,7 +26,7 @@ const addOptionRE = /AddOption[\s\n\r]*\([\s\n\r]*"([^"]+)"(.*?)\);/gs;
 const nodeOptionsText = cliText.match(/<!-- node-options-node start -->(.*)<!-- node-options-others end -->/s)[1];
 const v8OptionsText = cliText.match(/<!-- v8-options start -->(.*)<!-- v8-options end -->/s)[1];
 
-const manPage = path.join(rootDir, 'doc', 'node.1');
+const manPage = path.join(rootDir, 'out', 'doc', 'node.1');
 const manPageText = fs.readFileSync(manPage, { encoding: 'utf8' });
 
 // Documented in /doc/api/deprecations.md

test/doctool/test-manpage-options.mjs

@@ -1,9 +1,14 @@
-import '../common/index.mjs';
+import * as common from '../common/index.mjs';
+
 import assert from 'node:assert';
 import { createReadStream, readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { resolve, join } from 'node:path';
 
+if (common.isWindows) {
+  common.skip('`make doc` does not run on Windows');
+}
+
 // This test checks that all the CLI flags defined in the public CLI documentation (doc/api/cli.md)
 // are also documented in the manpage file (doc/node.1)
 // Note: the opposite (that all variables in doc/node.1 are documented in the CLI documentation)
@@ -14,7 +19,7 @@ const rootDir = resolve(import.meta.dirname, '..', '..');
 const cliMdPath = join(rootDir, 'doc', 'api', 'cli.md');
 const cliMdContentsStream = createReadStream(cliMdPath);
 
-const manPagePath = join(rootDir, 'doc', 'node.1');
+const manPagePath = join(rootDir, 'out', 'doc', 'node.1');
 const manPageContents = readFileSync(manPagePath, { encoding: 'utf8' });
 
 let insideOptionsSection = false;
@@ -50,7 +55,7 @@ for await (const line of rl) {
           flagNames.length === 1 ? '' : 's'
         } (present in \`doc/api/cli.md\`) ${flagNames.length === 1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${
           flagNames.map((flag) => `"-${flag}"`).join(', ')
-        }`
+        }`,
       );
     }
   }

tools/install.py

@@ -199,9 +199,9 @@ def files(options, action):
   action(options, [os.path.join(options.v8_dir, 'tools/lldb_commands.py')], 'share/doc/node/')
 
   if 'openbsd' in sys.platform:
-    action(options, ['doc/node.1'], 'man/man1/')
+    action(options, ['out/doc/node.1'], 'man/man1/')
   else:
-    action(options, ['doc/node.1'], 'share/man/man1/')
+    action(options, ['out/doc/node.1'], 'share/man/man1/')
 
   if 'true' == options.variables.get('node_install_npm'):
     npm_files(options, action)