Skip to content

Commit e45645a

Browse files
avivkelleravivkeller
authored
feat(config): pass more configuration to components (#737)
1 parent bddffe8 commit e45645a

39 files changed

+702
-624
lines changed

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@node-core/doc-kit",
33
"type": "module",
4-
"version": "1.2.1",
4+
"version": "1.3.0",
55
"repository": {
66
"type": "git",
77
"url": "git+https://github.com/nodejs/doc-kit.git"

‎scripts/update-type-map.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { writeFile } from 'node:fs/promises';
22

33
import { MDN_COMPAT_URL, MDN_TYPE_MAP } from './constants.mjs';
4-
import { loadFromURL } from '../src/utils/url.mjs';
4+
import { loadFromURL } from '../src/utils/loaders.mjs';
55

66
const compat = JSON.parse(await loadFromURL(MDN_COMPAT_URL));
77

‎src/generators/jsx-ast/README.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,7 @@ The `jsx-ast` generator converts MDAST (Markdown Abstract Syntax Tree) to JSX AS
66

77
The `jsx-ast` generator accepts the following configuration options:
88

9-
| Name | Type | Default | Description |
10-
| --------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------ |
11-
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
12-
| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
13-
| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
14-
| `index` | `array` | - | Array of `{ section, api }` objects defining the documentation structure |
9+
| Name | Type | Default | Description |
10+
| ------- | -------- | -------- | ------------------------------------------------------------------------ |
11+
| `ref` | `string` | `'main'` | Git reference/branch for linking to source files |
12+
| `index` | `array` | - | Array of `{ section, api }` objects defining the documentation structure |

‎src/generators/jsx-ast/generate.mjs‎

Lines changed: 3 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
1-
import { buildSideBarProps } from './utils/buildBarProps.mjs';
21
import buildContent from './utils/buildContent.mjs';
32
import { getSortedHeadNodes } from './utils/getSortedHeadNodes.mjs';
43
import { groupNodesByModule } from '../../utils/generators.mjs';
5-
import { getRemarkRecma } from '../../utils/remark.mjs';
6-
import { relative } from '../../utils/url.mjs';
7-
8-
const remarkRecma = getRemarkRecma();
94

105
/**
116
* Process a chunk of items in a worker thread.
@@ -16,28 +11,13 @@ const remarkRecma = getRemarkRecma();
1611
*
1712
* @type {import('./types').Generator['processChunk']}
1813
*/
19-
export async function processChunk(slicedInput, itemIndices, docPages) {
14+
export async function processChunk(slicedInput, itemIndices) {
2015
const results = [];
2116

2217
for (const idx of itemIndices) {
2318
const { head, entries } = slicedInput[idx];
2419

25-
const sideBarProps = buildSideBarProps(
26-
head,
27-
docPages.map(([heading, path]) => [
28-
heading,
29-
head.path === path
30-
? `${head.basename}.html`
31-
: `${relative(path, head.path)}.html`,
32-
])
33-
);
34-
35-
const content = await buildContent(
36-
entries,
37-
head,
38-
sideBarProps,
39-
remarkRecma
40-
);
20+
const content = await buildContent(entries, head);
4121

4222
results.push(content);
4323
}
@@ -55,16 +35,14 @@ export async function* generate(input, worker) {
5535

5636
const headNodes = getSortedHeadNodes(input);
5737

58-
const docPages = headNodes.map(node => [node.heading.data.name, node.path]);
59-
6038
// Create sliced input: each item contains head + its module's entries
6139
// This avoids sending all 4700+ entries to every worker
6240
const entries = headNodes.map(head => ({
6341
head,
6442
entries: groupedModules.get(head.api),
6543
}));
6644

67-
for await (const chunkResult of worker.stream(entries, docPages)) {
45+
for await (const chunkResult of worker.stream(entries)) {
6846
yield chunkResult;
6947
}
7048
}

‎src/generators/jsx-ast/index.mjs‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
'use strict';
22

3-
import { GITHUB_EDIT_URL } from '../../utils/configuration/templates.mjs';
43
import { createLazyGenerator } from '../../utils/generators.mjs';
54

65
/**
@@ -19,8 +18,6 @@ export default createLazyGenerator({
1918

2019
defaultConfiguration: {
2120
ref: 'main',
22-
pageURL: '{baseURL}/latest-{version}/api{path}.html',
23-
editURL: `${GITHUB_EDIT_URL}/doc/api{path}.md`,
2421
},
2522

2623
hasParallelProcessor: true,

‎src/generators/jsx-ast/types.d.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ export type Generator = GeneratorMetadata<
99
Generate<Array<MetadataEntry>, AsyncGenerator<JSXContent>>,
1010
ProcessChunk<
1111
{ head: MetadataEntry; entries: Array<MetadataEntry> },
12-
JSXContent,
13-
Array<[string, string]>
12+
JSXContent
1413
>
1514
>;

‎src/generators/jsx-ast/utils/__tests__/buildBarProps.test.mjs‎

Lines changed: 35 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,8 @@
11
import assert from 'node:assert/strict';
2-
import { describe, it, mock } from 'node:test';
2+
import { describe, it } from 'node:test';
33

4-
import { SemVer } from 'semver';
5-
6-
import { setConfig } from '../../../../utils/configuration/index.mjs';
7-
import * as generatorsExports from '../../../../utils/generators.mjs';
8-
9-
mock.module('reading-time', {
10-
defaultExport: () => ({ text: '5 min read' }),
11-
});
12-
13-
mock.module('../../../../utils/generators.mjs', {
14-
namedExports: {
15-
...generatorsExports,
16-
getCompatibleVersions: () => [
17-
{ version: '18.0.0', isLts: true, isCurrent: false },
18-
{ version: '19.0.0', isLts: false, isCurrent: true },
19-
],
20-
leftHandAssign: Object.assign,
21-
getVersionFromSemVer: version => `${version.major}.x`,
22-
getVersionURL: (version, api) => `/api/${version}/${api}`,
23-
},
24-
});
25-
26-
const {
27-
extractTextContent,
28-
buildMetaBarProps,
29-
formatVersionOptions,
30-
buildSideBarProps,
31-
} = await import('../buildBarProps.mjs');
32-
33-
await setConfig({
34-
version: 'v17.0.0',
35-
changelog: [
36-
{ version: new SemVer('16.0.0'), isLts: true, isCurrent: false },
37-
{ version: new SemVer('17.0.0'), isLts: false, isCurrent: true },
38-
],
39-
});
4+
const { extractTextContent, extractHeadings } =
5+
await import('../buildBarProps.mjs');
406

417
describe('extractTextContent', () => {
428
it('combines text and code node values from entries', () => {
@@ -66,104 +32,55 @@ describe('extractTextContent', () => {
6632
});
6733
});
6834

69-
describe('buildMetaBarProps', () => {
70-
it('creates meta bar properties from entries', () => {
71-
const head = {
72-
basename: 'fs',
73-
path: '/fs',
74-
added: 'v1.0.0',
75-
};
76-
35+
describe('extractHeadings', () => {
36+
it('extracts headings from entries that qualify for ToC', () => {
7737
const entries = [
7838
{
79-
content: {
80-
type: 'root',
81-
children: [{ type: 'text', value: 'Content' }],
39+
heading: {
40+
depth: 2,
41+
data: {
42+
text: 'fs.readFile(path)',
43+
name: 'readFile',
44+
slug: 'fs-readfile',
45+
type: 'method',
46+
},
8247
},
48+
stability: { data: { index: '2' } },
49+
},
50+
{
8351
heading: {
8452
depth: 2,
8553
data: {
86-
text: 'Heading',
87-
name: 'Heading',
88-
slug: 'heading',
89-
depth: 2,
54+
text: 'fs.writeFile(path)',
55+
name: 'writeFile',
56+
slug: 'fs-writefile',
57+
type: 'method',
9058
},
9159
},
60+
stability: null,
9261
},
9362
];
9463

95-
const result = buildMetaBarProps(head, entries);
96-
97-
assert.equal(result.addedIn, 'v1.0.0');
98-
assert.equal(result.readingTime, '5 min read');
99-
assert.deepEqual(result.viewAs, [
100-
['JSON', 'fs.json'],
101-
['MD', 'fs.md'],
102-
]);
103-
assert.equal(
104-
result.editThisPage,
105-
'https://github.com/nodejs/node/edit/main/doc/api/fs.md'
106-
);
107-
assert.ok(Array.isArray(result.headings));
108-
});
109-
110-
it('falls back to introduced_in if added is missing', () => {
111-
const head = {
112-
api: 'fs',
113-
introduced_in: 'v2.0.0',
114-
};
115-
116-
const entries = [];
64+
const result = extractHeadings(entries);
11765

118-
const result = buildMetaBarProps(head, entries);
119-
assert.equal(result.addedIn, 'v2.0.0');
66+
assert.equal(result.length, 2);
67+
assert.equal(result[0].slug, 'fs-readfile');
68+
assert.equal(result[0].depth, 2);
69+
assert.equal(result[0].stability, 2);
70+
assert.equal(result[1].stability, 2);
12071
});
121-
});
122-
123-
describe('formatVersionOptions', () => {
124-
it('formats version options with proper labels', () => {
125-
const versions = [
126-
{ version: new SemVer('16.0.0'), isLts: true, isCurrent: false },
127-
{ version: new SemVer('17.0.0'), isLts: false, isCurrent: true },
128-
{ version: new SemVer('18.0.0'), isLts: false, isCurrent: false },
129-
];
13072

131-
const result = formatVersionOptions(versions, '/http');
132-
133-
assert.deepStrictEqual(result, [
134-
{
135-
value: 'https://nodejs.org/docs/latest-v16.x/api/http.html',
136-
label: 'v16.x (LTS)',
137-
},
138-
{
139-
value: 'https://nodejs.org/docs/latest-v17.x/api/http.html',
140-
label: 'v17.x (Current)',
141-
},
73+
it('filters out entries with empty heading text', () => {
74+
const entries = [
14275
{
143-
value: 'https://nodejs.org/docs/latest-v18.x/api/http.html',
144-
label: 'v18.x',
76+
heading: {
77+
depth: 2,
78+
data: { text: '', name: '', slug: '', type: 'method' },
79+
},
14580
},
146-
]);
147-
});
148-
});
149-
150-
describe('buildSideBarProps', () => {
151-
it('creates sidebar properties with versions and navigation', () => {
152-
const entry = {
153-
path: 'http',
154-
basename: 'http',
155-
introduced_in: 'v0.10.0',
156-
};
157-
158-
const docPages = [
159-
['HTTP', 'http.html'],
160-
['HTTPS', 'https.html'],
16181
];
16282

163-
const result = buildSideBarProps(entry, docPages);
164-
165-
assert.equal(result.currentVersion, 'v17.0.0');
166-
assert.equal(result.pathname, 'http.html');
167-
assert.deepEqual(result.docPages, docPages);
83+
const result = extractHeadings(entries);
84+
assert.equal(result.length, 0);
16885
});
16986
});

0 commit comments

Comments
 (0)