Skip to content

Commit 54a250e

Browse files
targosrichardlau
targos
authored and
richardlau
committed
tools: update doctool dependencies, migrate to ESM
- Migrated to ESM because some dependencies now require it. - Did not update `highlight.js` to v11 because it has many breaking changes. - Used non-deprecated `highlight.js` API. Refs: highlightjs/highlight.js#2277 Fixes: #38938 Co-authored-by: Antoine du Hamel <[email protected]> PR-URL: #38966 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Anto Aravinth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
1 parent dcfb182 commit 54a250e

26 files changed

Lines changed: 658 additions & 427 deletions

‎Makefile‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -336,7 +336,7 @@ test-valgrind: all
336336
test-check-deopts: all
337337
$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) --check-deopts parallel sequential
338338

339-
DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.js doc/api/addons.md
339+
DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.mjs doc/api/addons.md
340340

341341
ifeq ($(OSTYPE),aix)
342342
DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
@@ -587,12 +587,12 @@ test-doc: doc-only lint-md ## Builds, lints, and verifies the docs.
587587
else \
588588
$(PYTHON) tools/test.py $(PARALLEL_ARGS) doctool; \
589589
fi
590-
$(NODE) tools/doc/checkLinks.js .
590+
$(NODE) tools/doc/checkLinks.mjs .
591591

592592
.PHONY: test-doc-ci
593593
test-doc-ci: doc-only
594594
$(PYTHON) tools/test.py --shell $(NODE) $(TEST_CI_ARGS) $(PARALLEL_ARGS) doctool
595-
$(NODE) tools/doc/checkLinks.js .
595+
$(NODE) tools/doc/checkLinks.mjs .
596596

597597
test-known-issues: all
598598
$(PYTHON) tools/test.py $(PARALLEL_ARGS) known_issues
@@ -734,33 +734,33 @@ run-npm-ci = $(PWD)/$(NPM) ci
734734

735735
LINK_DATA = out/doc/apilinks.json
736736
VERSIONS_DATA = out/previous-doc-versions.json
737-
gen-api = tools/doc/generate.js --node-version=$(FULLVERSION) \
737+
gen-api = tools/doc/generate.mjs --node-version=$(FULLVERSION) \
738738
--apilinks=$(LINK_DATA) $< --output-directory=out/doc/api \
739739
--versions-file=$(VERSIONS_DATA)
740-
gen-apilink = tools/doc/apilinks.js $(LINK_DATA) $(wildcard lib/*.js)
740+
gen-apilink = tools/doc/apilinks.mjs $(LINK_DATA) $(wildcard lib/*.js)
741741

742-
$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js | out/doc
742+
$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.mjs | out/doc
743743
$(call available-node, $(gen-apilink))
744744

745745
# Regenerate previous versions data if the current version changes
746-
$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.js
747-
$(call available-node, tools/doc/versions.js $@)
746+
$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.mjs
747+
$(call available-node, tools/doc/versions.mjs $@)
748748

749-
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
750-
tools/doc/markdown.js tools/doc/html.js tools/doc/json.js \
751-
tools/doc/apilinks.js $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api
749+
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.mjs \
750+
tools/doc/markdown.mjs tools/doc/html.mjs tools/doc/json.mjs \
751+
tools/doc/apilinks.mjs $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api
752752
$(call available-node, $(gen-api))
753753

754-
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \
755-
tools/doc/apilinks.js | out/doc/api
756-
$(call available-node, tools/doc/allhtml.js)
754+
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.mjs \
755+
tools/doc/apilinks.mjs | out/doc/api
756+
$(call available-node, tools/doc/allhtml.mjs)
757757

758-
out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.js | out/doc/api
759-
$(call available-node, tools/doc/alljson.js)
758+
out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.mjs | out/doc/api
759+
$(call available-node, tools/doc/alljson.mjs)
760760

761761
.PHONY: out/doc/api/stability
762-
out/doc/api/stability: out/doc/api/all.json tools/doc/stability.js | out/doc/api
763-
$(call available-node, tools/doc/stability.js)
762+
out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/api
763+
$(call available-node, tools/doc/stability.mjs)
764764

765765
.PHONY: docopen
766766
docopen: out/doc/api/all.html

‎doc/api/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<!--
22
NB(chrisdickinson): if you move this file, be sure to update
3-
tools/doc/html.js to point at the new location.
3+
tools/doc/html.mjs to point at the new location.
44
-->
55

66
<!--introduced_in=v0.10.0-->

‎test/common/index.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ const {
3030
allowGlobals,
3131
mustCall,
3232
mustCallAtLeast,
33+
mustSucceed,
3334
hasMultiLocalhost,
3435
skipIfDumbTerminal,
3536
skipIfEslintMissing,
@@ -76,6 +77,7 @@ export {
7677
allowGlobals,
7778
mustCall,
7879
mustCallAtLeast,
80+
mustSucceed,
7981
hasMultiLocalhost,
8082
skipIfDumbTerminal,
8183
skipIfEslintMissing,

test/doctool/test-apilinks.js renamed to test/doctool/test-apilinks.mjs

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
1-
'use strict';
2-
3-
require('../common');
4-
const fixtures = require('../common/fixtures');
5-
const tmpdir = require('../common/tmpdir');
6-
const fs = require('fs');
7-
const assert = require('assert');
8-
const path = require('path');
9-
const { execFileSync } = require('child_process');
10-
11-
const script = path.join(__dirname, '..', '..', 'tools', 'doc', 'apilinks.js');
1+
import '../common/index.mjs';
2+
import * as fixtures from '../common/fixtures.mjs';
3+
import tmpdir from '../common/tmpdir.js';
4+
5+
import assert from 'assert';
6+
import { execFileSync } from 'child_process';
7+
import fs from 'fs';
8+
import path from 'path';
9+
import { fileURLToPath } from 'url';
10+
11+
const script = fileURLToPath(
12+
new URL('../../tools/doc/apilinks.mjs', import.meta.url));
1213
const apilinks = fixtures.path('apilinks');
1314

1415
tmpdir.refresh();

test/doctool/test-doctool-html.js renamed to test/doctool/test-doctool-html.mjs

Lines changed: 8 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,14 @@
1-
'use strict';
1+
import '../common/index.mjs';
2+
import * as fixtures from '../common/fixtures.mjs';
23

3-
const common = require('../common');
4-
// The doctool currently uses js-yaml from the tool/node_modules/eslint/ tree.
5-
try {
6-
require('../../tools/node_modules/eslint/node_modules/js-yaml');
7-
} catch {
8-
common.skip('missing js-yaml (eslint not present)');
9-
}
4+
import assert from 'assert';
5+
import { readFileSync } from 'fs';
6+
import { createRequire } from 'module';
107

11-
const assert = require('assert');
12-
const { readFileSync } = require('fs');
13-
const fixtures = require('../common/fixtures');
14-
const { replaceLinks } = require('../../tools/doc/markdown.js');
15-
const html = require('../../tools/doc/html.js');
16-
const path = require('path');
8+
import * as html from '../../tools/doc/html.mjs';
9+
import { replaceLinks } from '../../tools/doc/markdown.mjs';
1710

18-
module.paths.unshift(
19-
path.join(__dirname, '..', '..', 'tools', 'doc', 'node_modules'));
11+
const require = createRequire(new URL('../../tools/doc/', import.meta.url));
2012
const unified = require('unified');
2113
const markdown = require('remark-parse');
2214
const remark2rehype = require('remark-rehype');

test/doctool/test-doctool-json.js renamed to test/doctool/test-doctool-json.mjs

Lines changed: 7 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,13 @@
1-
'use strict';
1+
import * as common from '../common/index.mjs';
2+
import * as fixtures from '../common/fixtures.mjs';
23

3-
const common = require('../common');
4-
// The doctool currently uses js-yaml from the tool/node_modules/eslint/ tree.
5-
try {
6-
require('../../tools/node_modules/eslint/node_modules/js-yaml');
7-
} catch {
8-
common.skip('missing js-yaml (eslint not present)');
9-
}
4+
import assert from 'assert';
5+
import fs from 'fs';
6+
import { createRequire } from 'module';
107

11-
const assert = require('assert');
12-
const fs = require('fs');
13-
const path = require('path');
14-
const fixtures = require('../common/fixtures');
15-
const json = require('../../tools/doc/json.js');
8+
import * as json from '../../tools/doc/json.mjs';
169

17-
module.paths.unshift(
18-
path.join(__dirname, '..', '..', 'tools', 'doc', 'node_modules'));
10+
const require = createRequire(new URL('../../tools/doc/', import.meta.url));
1911
const unified = require('unified');
2012
const markdown = require('remark-parse');
2113

test/doctool/test-doctool-versions.js renamed to test/doctool/test-doctool-versions.mjs

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
1-
'use strict';
1+
import '../common/index.mjs';
2+
import tmpdir from '../common/tmpdir.js';
23

3-
require('../common');
4-
const assert = require('assert');
5-
const { spawnSync } = require('child_process');
6-
const fs = require('fs');
7-
const path = require('path');
8-
const tmpdir = require('../common/tmpdir');
9-
const util = require('util');
4+
import assert from 'assert';
5+
import { spawnSync } from 'child_process';
6+
import fs from 'fs';
7+
import path from 'path';
8+
import { fileURLToPath } from 'url';
9+
import util from 'util';
1010

1111
const debuglog = util.debuglog('test');
12-
const versionsTool = path.resolve(__dirname, '../../tools/doc/versions.js');
12+
const versionsTool = fileURLToPath(
13+
new URL('../../tools/doc/versions.mjs', import.meta.url));
1314

1415
// At the time of writing these are the minimum expected versions.
1516
// New versions of Node.js do not have to be explicitly added here.

test/doctool/test-local-md-file-reference-regex.js renamed to test/doctool/test-local-md-file-reference-regex.mjs

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
'use strict';
1+
import '../common/index.mjs';
22

3-
require('../common');
4-
const assert = require('assert');
3+
import assert from 'assert';
54

6-
const { referenceToLocalMdFile } = require('../../tools/doc/markdown.js');
5+
import { referenceToLocalMdFile } from '../../tools/doc/markdown.mjs';
76

87
{
98
const shouldBeSpotted = [

test/doctool/test-make-doc.js renamed to test/doctool/test-make-doc.mjs

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
1-
'use strict';
2-
const common = require('../common');
1+
import * as common from '../common/index.mjs';
2+
3+
import assert from 'assert';
4+
import fs from 'fs';
5+
import path from 'path';
6+
37
if (common.isWindows) {
48
common.skip('`make doc` does not run on Windows');
59
}
610

711
// This tests that `make doc` generates the documentation properly.
812
// Note that for this test to pass, `make doc` must be run first.
913

10-
const assert = require('assert');
11-
const fs = require('fs');
12-
const path = require('path');
13-
14-
const apiPath = path.resolve(__dirname, '..', '..', 'out', 'doc', 'api');
15-
const mdPath = path.resolve(__dirname, '..', '..', 'doc', 'api');
16-
const allMD = fs.readdirSync(mdPath);
17-
const allDocs = fs.readdirSync(apiPath);
14+
const apiURL = new URL('../../out/doc/api/', import.meta.url);
15+
const mdURL = new URL('../../doc/api/', import.meta.url);
16+
const allMD = fs.readdirSync(mdURL);
17+
const allDocs = fs.readdirSync(apiURL);
1818
assert.ok(allDocs.includes('index.html'));
1919

2020
const actualDocs = allDocs.filter(
@@ -33,7 +33,7 @@ for (const name of actualDocs) {
3333
);
3434
}
3535

36-
const toc = fs.readFileSync(path.resolve(apiPath, 'index.html'), 'utf8');
36+
const toc = fs.readFileSync(new URL('./index.html', apiURL), 'utf8');
3737
const re = /href="([^/]+\.html)"/;
3838
const globalRe = new RegExp(re, 'g');
3939
const links = toc.match(globalRe);
@@ -56,8 +56,9 @@ for (const actualDoc of actualDocs) {
5656
assert.ok(
5757
expectedDocs.includes(actualDoc), `${actualDoc} does not match TOC`);
5858

59-
assert.ok(
60-
fs.statSync(path.join(apiPath, actualDoc)).size !== 0,
59+
assert.notStrictEqual(
60+
fs.statSync(new URL(`./${actualDoc}`, apiURL)).size,
61+
0,
6162
`${actualDoc} is empty`
6263
);
6364
}

‎tools/doc/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ added: v0.10.0
7878

7979
* Returns: {SomeClass | null} The next `SomeClass` in line.
8080

81-
`SomeClass` must be registered in `tools/doc/type-parser.js`
81+
`SomeClass` must be registered in `tools/doc/type-parser.mjs`
8282
to be properly parsed in `{type}` fields.
8383

8484
### SomeClass.someProperty

0 commit comments

Comments
 (0)