Skip to content

Commit a1d0aef

Browse files
targosdanielleadams
targos
authored and
danielleadams
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 902bb85 commit a1d0aef

26 files changed

Lines changed: 658 additions & 427 deletions

‎Makefile‎

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

341-
DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.js doc/api/addons.md
341+
DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.mjs doc/api/addons.md
342342

343343
ifeq ($(OSTYPE),aix)
344344
DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
@@ -589,12 +589,12 @@ test-doc: doc-only lint-md ## Builds, lints, and verifies the docs.
589589
else \
590590
$(PYTHON) tools/test.py $(PARALLEL_ARGS) doctool; \
591591
fi
592-
$(NODE) tools/doc/checkLinks.js .
592+
$(NODE) tools/doc/checkLinks.mjs .
593593

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

599599
test-known-issues: all
600600
$(PYTHON) tools/test.py $(PARALLEL_ARGS) known_issues
@@ -736,33 +736,33 @@ run-npm-ci = $(PWD)/$(NPM) ci
736736

737737
LINK_DATA = out/doc/apilinks.json
738738
VERSIONS_DATA = out/previous-doc-versions.json
739-
gen-api = tools/doc/generate.js --node-version=$(FULLVERSION) \
739+
gen-api = tools/doc/generate.mjs --node-version=$(FULLVERSION) \
740740
--apilinks=$(LINK_DATA) $< --output-directory=out/doc/api \
741741
--versions-file=$(VERSIONS_DATA)
742-
gen-apilink = tools/doc/apilinks.js $(LINK_DATA) $(wildcard lib/*.js)
742+
gen-apilink = tools/doc/apilinks.mjs $(LINK_DATA) $(wildcard lib/*.js)
743743

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

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

751-
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
752-
tools/doc/markdown.js tools/doc/html.js tools/doc/json.js \
753-
tools/doc/apilinks.js $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api
751+
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.mjs \
752+
tools/doc/markdown.mjs tools/doc/html.mjs tools/doc/json.mjs \
753+
tools/doc/apilinks.mjs $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api
754754
$(call available-node, $(gen-api))
755755

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

760-
out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.js | out/doc/api
761-
$(call available-node, tools/doc/alljson.js)
760+
out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.mjs | out/doc/api
761+
$(call available-node, tools/doc/alljson.mjs)
762762

763763
.PHONY: out/doc/api/stability
764-
out/doc/api/stability: out/doc/api/all.json tools/doc/stability.js | out/doc/api
765-
$(call available-node, tools/doc/stability.js)
764+
out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/api
765+
$(call available-node, tools/doc/stability.mjs)
766766

767767
.PHONY: docopen
768768
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,
@@ -75,6 +76,7 @@ export {
7576
allowGlobals,
7677
mustCall,
7778
mustCallAtLeast,
79+
mustSucceed,
7880
hasMultiLocalhost,
7981
skipIfDumbTerminal,
8082
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)