Revert "build, doc: move to redesign"

This reverts commit 18a9ba509a.

PR-URL: https://github.com/nodejs/node/pull/67015
Refs: https://github.com/nodejs/node/issues/66571
Reviewed-By: Claudio Wunder <cwunder@gnome.org>
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
Reviewed-By: Aviv Keller <me@aviv.sh>

.github/dependabot.yml

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

.github/workflows/build-tarball.yml

@@ -67,7 +67,6 @@ env:
   PYTHON_VERSION: '3.15'
   FLAKY_TESTS: keep_retrying
   CLANG_VERSION: '19'
-  NODE_VERSION: lts/*
 
 permissions:
   contents: read
@@ -85,10 +84,6 @@ 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

@@ -402,7 +402,7 @@ ifeq ($(OSTYPE),os400)
 DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
 endif
 
-DOC_KIT ?= tools/doc/node_modules/@doc-kit/cli/bin/cli.mjs
+DOC_KIT ?= tools/doc/node_modules/@node-core/doc-kit/bin/cli.mjs
 
 node_use_openssl_and_icu = $(call available-node,"-p" \
 			 "process.versions.openssl != undefined && process.versions.icu != undefined")
@@ -871,7 +871,7 @@ VERSION=v$(RAWVER)
 
 .PHONY: doc-only
 .NOTPARALLEL: doc-only
-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.
+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.
 
 .PHONY: doc
 doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary.
@@ -908,10 +908,15 @@ $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json &: $(a
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			--log-level debug \
-			--config-file tools/doc/web.doc-kit.config.mjs \
+			-t legacy-html-all \
+			-t legacy-json-all \
+			-i doc/api/*.md \
+			--ignore $(skip_apidoc_files) \
+			-o out/doc/api \
+			-c ./CHANGELOG.md \
 			-v $(VERSION) \
-			$(if $(JOBS),-p $(JOBS)) \
+			--index doc/api/index.md \
+			--type-map doc/type-map.json \
 		) \
 	fi
 endif
@@ -922,10 +927,13 @@ 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
 
@@ -935,9 +943,12 @@ out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc
 	else \
 		$(call available-node, \
 			$(DOC_KIT) generate \
-			--config-file tools/doc/api-links.doc-kit.config.mjs \
+			-t api-links \
+			-i lib/*.js \
 			-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 Node.js's doc-kit tool.
+.\" This file was generated automatically by the @node-core/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 node.1`.
+.\" To regenerate this file, run `make doc/node.1`.
 .\"
 .\"======================================================================
 .Dd $Mdocdate$
@@ -274,7 +274,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.
@@ -452,11 +452,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.
@@ -1993,7 +1993,7 @@ Print node's version.
 .It Fl -vfs-load Ns = Ns Ar source
 .Bl -bullet
 .It
-\fBsource\fR \fB{string}\fR A directory or an archive file to mount and run.
+\fBsource\fR \fB<string>\fR A directory or an archive file to mount and run.
 .El
 May be given at most once.
 Mounts \fBsource\fR as a virtual file system (\fBnode:vfs\fR), and runs the entry

test/doctool/test-make-doc.mjs

@@ -0,0 +1,74 @@
+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

@@ -1,17 +0,0 @@
-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,9 +2,6 @@
   "name": "doc",
   "private": true,
   "dependencies": {
-    "@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"
+    "@node-core/doc-kit": "1.4.1"
   }
 }

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

@@ -1,53 +0,0 @@
-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

@@ -231,7 +231,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\@doc-kit\cli\bin\cli.mjs"
+set "doc_kit_exe="%~dp0%node_exe%" %~dp0tools\doc\node_modules\@node-core\doc-kit\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"
 
@@ -716,15 +716,13 @@ robocopy /e doc\api %config%\doc\api
 
 %doc_kit_exe% ^
   generate ^
-  --config-file "%~dp0tools\doc\web.doc-kit.config.mjs" ^
+  -t legacy-html-all legacy-json-all api-links ^
+  -i doc/api/*.md ^
+  -i lib/*.js ^
   -o %config%/doc/api/ ^
-  -v %NODE_VERSION%
-
-%doc_kit_exe% ^
-  generate ^
-  --config-file "%~dp0tools\doc\api-links.doc-kit.config.mjs" ^
-  -o %config%/doc/api/ ^
-  -v %NODE_VERSION%
+  -c file://%~dp0\CHANGELOG.md ^
+  -v %NODE_VERSION% ^
+  --type-map "file://%~dp0doc\type-map.json"
 
 :run
 @rem Run tests if requested.