build, doc: move to redesign

Signed-off-by: Aviv Keller <me@aviv.sh>
PR-URL: https://github.com/nodejs/node/pull/62045
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Tim Perry <pimterry@gmail.com>

.github/dependabot.yml

@@ -53,7 +53,8 @@ updates:
       semver-minor-days: 5
       semver-patch-days: 5
       exclude:
-        - '@node-core/doc-kit'
+        - '@doc-kit/*'
+        - '@node-core/*'
     commit-message:
       prefix: tools
     open-pull-requests-limit: 10

.github/workflows/build-tarball.yml

@@ -67,6 +67,7 @@ env:
   PYTHON_VERSION: '3.14'
   FLAKY_TESTS: keep_retrying
   CLANG_VERSION: '19'
+  NODE_VERSION: lts/*
 
 permissions:
   contents: read
@@ -84,6 +85,10 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
           allow-prereleases: true
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
       - name: Make tarball
         run: |
           export DISTTYPE=nightly

Makefile

@@ -389,7 +389,7 @@ ifeq ($(OSTYPE),os400)
 DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
 endif
 
-DOC_KIT ?= tools/doc/node_modules/@node-core/doc-kit/bin/cli.mjs
+DOC_KIT ?= tools/doc/node_modules/@doc-kit/cli/bin/cli.mjs
 
 node_use_openssl_and_icu = $(call available-node,"-p" \
 			 "process.versions.openssl != undefined && process.versions.icu != undefined")
@@ -858,7 +858,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/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.
@@ -895,15 +895,10 @@ $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json &: $(a
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			-t legacy-html-all \
-			-t legacy-json-all \
-			-i doc/api/*.md \
-			--ignore $(skip_apidoc_files) \
-			-o out/doc/api \
-			-c ./CHANGELOG.md \
+			--log-level debug \
+			--config-file tools/doc/web.doc-kit.config.mjs \
 			-v $(VERSION) \
-			--index doc/api/index.md \
-			--type-map doc/type-map.json \
+			$(if $(JOBS),-p $(JOBS)) \
 		) \
 	fi
 endif
@@ -914,13 +909,10 @@ out/doc/llms.txt: $(apidoc_sources) tools/doc/node_modules | out/doc
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
+			--config-file tools/doc/web.doc-kit.config.mjs \
 			-t llms-txt \
-			-i doc/api/*.md \
-			--ignore $(skip_apidoc_files) \
 			-o $(@D) \
-			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			--type-map doc/type-map.json \
 		) \
 	fi
 
@@ -930,12 +922,9 @@ out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			-t api-links \
-			-i lib/*.js \
+			--config-file tools/doc/api-links.doc-kit.config.mjs \
 			-o $(@D) \
-			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			--type-map doc/type-map.json \
 		) \
 	fi
 

doc/node.1

@@ -1,9 +1,9 @@
 .\"
-.\" This file was generated automatically by the @node-core/doc-kit tool.
+.\" This file was generated automatically by Node.js's doc-kit tool.
 .\" Please do not edit this file manually. Make any updates to cli.md
 .\" and regenerate the file afterward.
 .\"
-.\" To regenerate this file, run `make doc/node.1`.
+.\" To regenerate this file, run `make node.1`.
 .\"
 .\"======================================================================
 .Dd $Mdocdate$
@@ -236,7 +236,7 @@ Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --a
 .It Fl -allow-openssl-store
 When using the Permission Model, the process will not be able to use
 OpenSSL STORE loaders by default, for example to load a private key from a
-\fB<URL>\fR passed to \fBcrypto.createPrivateKey()\fR. Attempts to do so will throw
+\fB{URL}\fR passed to \fBcrypto.createPrivateKey()\fR. Attempts to do so will throw
 an \fBERR_ACCESS_DENIED\fR unless the user explicitly passes the
 \fB--allow-openssl-store\fR flag. This permission can be dropped at runtime via
 \fBpermission.drop()\fR.
@@ -408,11 +408,11 @@ creation behavior.
 The following options are currently supported:
 .Bl -bullet
 .It
-\fBbuilder\fR \fB<string>\fR Required. Provides the name to the script that is executed
-before building the snapshot, as if \fB--build-snapshot\fR had been passed
+\fBbuilder\fR \fB{string}\fR Required. Provides the name to the script that is executed
+before building the snapshot, as if \fB--build-snapshot\fR had been passed
 with \fBbuilder\fR as the main script name.
 .It
-\fBwithoutCodeCache\fR \fB<boolean>\fR Optional. Including the code cache reduces the
+\fBwithoutCodeCache\fR \fB{boolean}\fR Optional. Including the code cache reduces the
 time spent on compiling functions included in the snapshot at the expense
 of a bigger snapshot size and potentially breaking portability of the
 snapshot.

test/doctool/test-make-doc.mjs

@@ -1,74 +0,0 @@
-import * as common from '../common/index.mjs';
-
-import assert from 'assert';
-import fs from 'fs';
-import path from 'path';
-
-if (common.isWindows) {
-  common.skip('`make doc` does not run on Windows');
-}
-
-// This tests that `make doc` generates the documentation properly.
-// Note that for this test to pass, `make doc` must be run first.
-
-const apiURL = new URL('../../out/doc/api/', import.meta.url);
-const mdURL = new URL('../../doc/api/', import.meta.url);
-const allMD = fs.readdirSync(mdURL);
-const allDocs = fs.readdirSync(apiURL);
-assert.ok(allDocs.includes('index.html'));
-
-const actualDocs = allDocs.filter(
-  (name) => {
-    const extension = path.extname(name);
-    return extension === '.html' || extension === '.json';
-  },
-);
-
-for (const name of actualDocs) {
-  if (name.startsWith('all.') || name === 'apilinks.json') continue;
-
-  assert.ok(
-    allMD.includes(name.replace(/\.\w+$/, '.md')),
-    `Unexpected output: out/doc/api/${name}, remove and rerun.`,
-  );
-}
-
-const toc = fs.readFileSync(new URL('./index.html', apiURL), 'utf8');
-const re = /href=("([^/]+\.html)"|([^/]+\.html))/;
-const globalRe = new RegExp(re, 'g');
-const links = toc.match(globalRe);
-assert.notStrictEqual(links, null);
-
-// Filter out duplicate links, leave just filenames, add expected JSON files.
-const linkedHtmls = [...new Set(links)].map((link) => link.match(re)[1])
-                      .concat(['index.html']);
-const expectedJsons = linkedHtmls
-                       .map((name) => name.replace('.html', '.json'));
-const expectedDocs = linkedHtmls.concat(expectedJsons);
-const renamedDocs = ['policy.json', 'policy.html'];
-const skipedDocs = ['dtls.json', 'dtls.html', 'quic.json', 'quic.html'];
-
-// Test that all the relative links in the TOC match to the actual documents.
-for (const expectedDoc of expectedDocs) {
-  if (skipedDocs.includes(expectedDoc)) continue;
-  assert.ok(actualDocs.includes(expectedDoc), `${expectedDoc} does not exist`);
-}
-
-// Test that all the actual documents match to the relative links in the TOC
-// and that they are not empty files.
-for (const actualDoc of actualDocs) {
-  // When renaming the documentation, the old url is lost
-  // Unless the old file is still available pointing to the correct location
-  // 301 redirects are not yet automated. So keeping the old URL is a
-  // reasonable workaround.
-  if (renamedDocs.includes(actualDoc) || skipedDocs.includes(actualDoc) ||
-      actualDoc === 'apilinks.json') continue;
-  assert.ok(
-    expectedDocs.includes(actualDoc), `${actualDoc} does not match TOC`);
-
-  assert.notStrictEqual(
-    fs.statSync(new URL(`./${actualDoc}`, apiURL)).size,
-    0,
-    `${actualDoc} is empty`,
-  );
-}

tools/doc/api-links.doc-kit.config.mjs

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const fromRoot = (path) =>
+  pathToFileURL(join(import.meta.dirname, '..', '..', path)).href;
+
+export default {
+  extends: '@node-core/doc-kit/config',
+
+  target: ['api-links'],
+
+  global: {
+    input: ['lib/*.js'],
+
+    changelog: fromRoot('CHANGELOG.md'),
+  },
+};

tools/doc/package.json

@@ -2,6 +2,9 @@
   "name": "doc",
   "private": true,
   "dependencies": {
-    "@node-core/doc-kit": "1.4.1"
+    "@doc-kit/cli": "1.0.2",
+    "@doc-kit/generator-react": "0.3.0",
+    "@node-core/doc-kit": "2.0.2",
+    "@node-core/doc-kit-legacy": "1.0.2"
   }
 }

tools/doc/web.doc-kit.config.mjs

@@ -0,0 +1,53 @@
+import { createRequire } from 'node:module';
+import { totalmem } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+// Gate HTML generation for high-memory machines
+//
+// TODO(@avivkeller): Lower the amount of memory
+// we use.
+const hasEnoughMemory = totalmem() > 5 * (1024 ** 3);
+
+// The HTML generator bundles its CSS with Lightning CSS, which ships as a
+// native binding that is not available on every platform we build on.
+// Probe for it up front and skip HTML generation when it cannot be loaded,
+// rather than failing partway through the build.
+//
+// TODO(@avivkeller): Fall back to WASM on machines
+// without native implementations of our dependencies
+const canLoadLightningCSS = () => {
+  try {
+    require('lightningcss');
+    return true;
+  } catch (error) {
+    console.warn(`Skipping HTML generation: unable to load lightningcss (${error.message.split('\n')[0]})`);
+    return false;
+  }
+};
+
+const fromRoot = (path) =>
+  pathToFileURL(join(import.meta.dirname, '..', '..', path)).href;
+
+export default {
+  extends: '@node-core/doc-kit/config',
+
+  target: [
+    'legacy-json-all',
+    hasEnoughMemory && canLoadLightningCSS() && 'section-pages',
+  ].filter(Boolean),
+
+  global: {
+    input: ['doc/api/*.md'],
+    ignore: ['doc/api/quic.md'],
+    output: 'out/doc/api',
+
+    changelog: fromRoot('CHANGELOG.md'),
+  },
+
+  metadata: {
+    typeMap: fromRoot('doc/type-map.json'),
+  },
+};

vcbuild.bat

@@ -229,7 +229,7 @@ if defined package set stage_package=1
 set "node_exe=%config%\node.exe"
 set "node_gyp_exe="%node_exe%" deps\npm\node_modules\node-gyp\bin\node-gyp"
 set "npm_exe="%~dp0%node_exe%" %~dp0deps\npm\bin\npm-cli.js"
-set "doc_kit_exe="%~dp0%node_exe%" %~dp0tools\doc\node_modules\@node-core\doc-kit\bin\cli.mjs"
+set "doc_kit_exe="%~dp0%node_exe%" %~dp0tools\doc\node_modules\@doc-kit\cli\bin\cli.mjs"
 if "%target_env%"=="vs2022" set "node_gyp_exe=%node_gyp_exe% --msvs_version=2022"
 if "%target_env%"=="vs2026" set "node_gyp_exe=%node_gyp_exe% --msvs_version=2026"
 
@@ -701,13 +701,15 @@ robocopy /e doc\api %config%\doc\api
 
 %doc_kit_exe% ^
   generate ^
-  -t legacy-html-all legacy-json-all api-links ^
-  -i doc/api/*.md ^
-  -i lib/*.js ^
+  --config-file "%~dp0tools\doc\web.doc-kit.config.mjs" ^
   -o %config%/doc/api/ ^
-  -c file://%~dp0\CHANGELOG.md ^
-  -v %NODE_VERSION% ^
-  --type-map "file://%~dp0doc\type-map.json"
+  -v %NODE_VERSION%
+
+%doc_kit_exe% ^
+  generate ^
+  --config-file "%~dp0tools\doc\api-links.doc-kit.config.mjs" ^
+  -o %config%/doc/api/ ^
+  -v %NODE_VERSION%
 
 :run
 @rem Run tests if requested.