build, doc: generate node.1 with doc-kit by avivkeller · Pull Request #62044 · nodejs/node

avivkeller · 2026-02-28T17:32:24Z

We recently moved node to build with doc-kit, the new tooling for documentation. doc-kit also provides a man-page generator, which PR changes core to use.

~~The tests for this generator are here, and as such, do not need to exist in this repository.~~

cc @nodejs/web-infra

nodejs-github-bot · 2026-02-28T17:32:29Z

Review requested:

@nodejs/build
@nodejs/config
@nodejs/tsc

aduh95 · 2026-02-28T17:37:11Z

The tests for this generator are here, and as such, do not need to exist in this repository.

I disagree, I think there's value in having tests on this repo so we can confidently approve updates or even that PR.

avivkeller · 2026-02-28T17:38:55Z

I disagree, I think there's value in having tests on this repo so we can confidently approve updates or even that PR.

Noted. I'll move the tests into the doctool tests, and test them with the rest of the documentation generator

codecov · 2026-02-28T19:05:30Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.64%. Comparing base (6a3d358) to head (f896722).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62044      +/-   ##
==========================================
+ Coverage   89.58%   89.64%   +0.06%     
==========================================
  Files         674      676       +2     
  Lines      205159   206240    +1081     
  Branches    39352    39510     +158     
==========================================
+ Hits       183792   184894    +1102     
+ Misses      13583    13465     -118     
- Partials     7784     7881      +97

Files with missing lines	Coverage Δ
src/node_options.cc	`76.22% <ø> (+0.02%)`	⬆️

... and 127 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-02-28T19:46:48Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71502/

Copilot

Pull request overview

This PR migrates the Node.js man page (node.1) generation to doc-kit and updates build/test/install paths accordingly, removing the previously checked-in doc/node.1 source.

Changes:

Generate out/doc/node.1 via doc-kit (make doc-only) and use it for packaging/install.
Update doctool tests to read the man page from out/doc/node.1.
Remove doc/node.1 from the repository and adjust related references.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/install.py	Installs the man page from `out/doc/node.1` instead of `doc/node.1`.
test/parallel/test-cli-node-options-docs.js	Removes man-page-based option/envvar cross-checking.
test/doctool/test-manpage-options.mjs	Updates manpage path to `out/doc/node.1` and adds Windows skip.
test/doctool/test-manpage-envvars.mjs	Updates manpage path to `out/doc/node.1` and adds Windows skip.
src/node_options.cc	Updates guidance comment to only mention `doc/api/cli.md`.
doc/node.1	Deletes the checked-in man page file.
Makefile	Adds `out/doc/node.1` generation rule and wires it into `doc-only`, `install`, and tarball creation.
BUILDING.md	Updates instructions to read the generated man page from `out/doc/node.1`.

Comments suppressed due to low confidence (4)

test/doctool/test-manpage-options.mjs:9

common is referenced but never imported/bound in this module. import '../common/index.mjs' only has side effects and does not define a common identifier, so this will throw a ReferenceError before the test can skip on Windows. Import it as a namespace (e.g., import * as common from '../common/index.mjs';) or otherwise ensure common is defined.
test/doctool/test-manpage-envvars.mjs:9
common is referenced but never imported/bound in this module. import '../common/index.mjs' does not create a common identifier, so this will throw a ReferenceError before the test can skip on Windows. Import it as a namespace (e.g., import * as common from '../common/index.mjs';).
test/doctool/test-manpage-options.mjs:58
The test now reads from out/doc/node.1, but the failure message still refers to doc/node.1, which will be confusing when this fails. Update the message to reference out/doc/node.1 (or interpolate the actual manPagePath).
test/doctool/test-manpage-envvars.mjs:26
This test now reads the man page from out/doc/node.1, but the assertion message still says it scanned doc/node.1. Update the message to match the actual path (ideally by including the computed manPagePath) so failures are actionable.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tools/install.py

Makefile

aduh95 · 2026-03-01T21:28:50Z

src/node_options.cc

-// XXX: If you add an option here, please also add it to doc/node.1 and
-// doc/api/cli.md
+// XXX: If you add an option here, please also add it to doc/api/cli.md
 // TODO(addaleax): Make that unnecessary.


The TODO can be considered resolved IMO, we already have test/parallel/test-cli-node-options-docs.js that validates both are in sync, so node.1 was the only remaining thing IIUC

Suggested change

// TODO(addaleax): Make that unnecessary.

aduh95 · 2026-03-01T21:31:04Z

BUILDING.md


 ```bash
-man doc/node.1
+man out/doc/node.1


Suggested change

man out/doc/node.1

make out/doc/node.1

man out/doc/node.1

aduh95 · 2026-03-01T21:35:14Z

Makefile

+out/doc/node.1: 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 doc/api/cli.md \
+			-o $(@D) \
+			-c ./CHANGELOG.md \
+			-v $(VERSION) \
+			--type-map doc/type-map.json \


We need to list the dependencies, otherwise make won't regenerate the man page. Why do we need to pass the CHANGELOG and the type-map? That seems out of place

Suggested change

out/doc/node.1: 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 doc/api/cli.md \

-o $(@D) \

-c ./CHANGELOG.md \

-v $(VERSION) \

--type-map doc/type-map.json \

out/doc/node.1: doc/api/cli.md CHANGELOG.md doc/type-map.json 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) \

-c ./CHANGELOG.md \

-v $(VERSION) \

--type-map doc/type-map.json \

We don't need to pass them, I suppose

aduh95 · 2026-03-01T21:37:53Z

Makefile

+	cp out/doc/node.1 $(TARNAME)/doc/node.1
 	cp -r out/doc/api/* $(TARNAME)/doc/api/


Could we simply copy the whole out/doc?

Suggested change

cp out/doc/node.1 $(TARNAME)/doc/node.1

cp -r out/doc/api/* $(TARNAME)/doc/api/

cp -r out/doc $(TARNAME)

I was thinking that, however, out/doc also contains apilinks.json, which we don't want to copy

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

ae3de90

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Feb 28, 2026

avivkeller marked this pull request as ready for review February 28, 2026 17:32

avivkeller added doc Issues and PRs related to the documentations. build Issues and PRs related to build files or the CI. cli Issues and PRs related to the Node.js command line interface. and removed lib / src Issues and PRs related to general changes in the lib or src directory. labels Feb 28, 2026

ovflowd approved these changes Feb 28, 2026

View reviewed changes

fixup!

747c861

avivkeller requested a review from aduh95 February 28, 2026 17:47

fixup!

f896722

avivkeller added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Feb 28, 2026

fixup!

a95e773

Copilot AI review requested due to automatic review settings March 1, 2026 21:11

Copilot started reviewing on behalf of avivkeller March 1, 2026 21:12 View session

Copilot AI reviewed Mar 1, 2026

View reviewed changes

tools/install.py Show resolved Hide resolved

Makefile Show resolved Hide resolved

fixup!

303d765

aduh95 reviewed Mar 1, 2026

View reviewed changes

		cp out/doc/node.1 $(TARNAME)/doc/node.1
		cp -r out/doc/api/* $(TARNAME)/doc/api/

	cp out/doc/node.1 $(TARNAME)/doc/node.1
	cp -r out/doc/api/* $(TARNAME)/doc/api/
	cp -r out/doc $(TARNAME)

Uh oh!

Conversation

avivkeller commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Feb 28, 2026

Uh oh!

aduh95 commented Feb 28, 2026

Uh oh!

avivkeller commented Feb 28, 2026

Uh oh!

codecov bot commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nodejs-github-bot commented Feb 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

aduh95 Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

avivkeller commented Feb 28, 2026 •

edited

Loading

codecov bot commented Feb 28, 2026 •

edited

Loading

aduh95 Mar 1, 2026 •

edited

Loading

aduh95 Mar 1, 2026 •

edited

Loading