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

[avivkeller]

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]

Review requested:

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

[aduh95]

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]

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]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.34%. Comparing base (17e4196) to head (2dae1ba).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62044      +/-   ##
==========================================
+ Coverage   90.33%   90.34%   +0.01%     
==========================================
  Files         732      732              
  Lines      236454   236507      +53     
  Branches    44540    44532       -8     
==========================================
+ Hits       213589   213679      +90     
+ Misses      14581    14540      -41     
- Partials     8284     8288       +4     

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

... and 49 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]

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.

[avivkeller]

@aduh95 any other concerns?

[github-actions]

Failed to start CI

   ⚠  Commits were pushed since the last approving review:
   ⚠  - build, doc: generate node.1 with doc-kit
   ✘  Refusing to run CI on potentially unsafe PR

https://github.com/nodejs/node/actions/runs/23118175264

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[aduh95]

There are conflicts to solve here

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[avivkeller]

Requesting re-review so I can land this w/ an approval

[ovflowd]

@avivkeller PR requires rebasing

[aduh95]

This needs a rebase

[avivkeller]

On it! Sorry for the delay!

[avivkeller]

ack! The Signed-off-by! I'll add that tomorrow

[avivkeller]

@aduh95 It's hard to keep this up to when conflicts keep arising due to the high edit count of the file. I'll rebase again, but any ideas how to improve the rebase + approve cycle on this PR to reduce the continued rebasing?