Skip to content

Commit a661ff6

Browse files
avivkelleravivkeller
committed
chore: improved index page
1 parent 9c18a58 commit a661ff6

6 files changed

Lines changed: 101 additions & 94 deletions

File tree

‎packages/core/src/utils/__tests__/generators.test.mjs‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,71 @@ import assert from 'node:assert/strict';
22
import { describe, it } from 'node:test';
33

44
import {
5+
getEntryDescription,
56
groupNodesByModule,
67
getVersionFromSemVer,
78
coerceSemVer,
89
getCompatibleVersions,
910
} from '../generators.mjs';
1011

12+
describe('getEntryDescription', () => {
13+
it('returns llm_description when available', () => {
14+
const entry = {
15+
llm_description: 'LLM generated description',
16+
content: { children: [] },
17+
};
18+
19+
const result = getEntryDescription(entry);
20+
assert.equal(result, 'LLM generated description');
21+
});
22+
23+
it('extracts first paragraph when no llm_description', () => {
24+
const entry = {
25+
content: {
26+
children: [
27+
{
28+
type: 'paragraph',
29+
children: [{ type: 'text', value: 'First paragraph' }],
30+
},
31+
],
32+
},
33+
};
34+
35+
const result = getEntryDescription(entry);
36+
assert.ok(result.length > 0);
37+
});
38+
39+
it('returns empty string when no paragraph found', () => {
40+
const entry = {
41+
content: {
42+
children: [
43+
{ type: 'heading', children: [{ type: 'text', value: 'Title' }] },
44+
],
45+
},
46+
};
47+
48+
const result = getEntryDescription(entry);
49+
assert.equal(result, '');
50+
});
51+
52+
it('removes newlines from description', () => {
53+
const entry = {
54+
content: {
55+
children: [
56+
{
57+
type: 'paragraph',
58+
children: [{ type: 'text', value: 'Line 1\nLine 2\r\nLine 3' }],
59+
},
60+
],
61+
},
62+
};
63+
64+
const result = getEntryDescription(entry);
65+
assert.equal(result.includes('\n'), false);
66+
assert.equal(result.includes('\r'), false);
67+
});
68+
});
69+
1170
describe('groupNodesByModule', () => {
1271
it('groups nodes by api property', () => {
1372
const nodes = [

‎packages/core/src/utils/generators.mjs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,36 @@
22

33
import { coerce, major } from 'semver';
44

5+
import { transformNodeToString } from './unist.mjs';
6+
7+
/**
8+
* Retrieves the description of a given API doc entry. It first checks whether
9+
* the entry has a llm_description property. If not, it extracts the first
10+
* paragraph from the entry's content.
11+
*
12+
* @param {import('../generators/metadata/types').MetadataEntry} entry
13+
* @returns {string}
14+
*/
15+
export const getEntryDescription = entry => {
16+
if (entry.llm_description) {
17+
return entry.llm_description.trim();
18+
}
19+
20+
const descriptionNode = entry.content.children.find(
21+
child => child.type === 'paragraph'
22+
);
23+
24+
if (!descriptionNode) {
25+
return '';
26+
}
27+
28+
return (
29+
transformNodeToString(descriptionNode)
30+
// Remove newlines and extra spaces
31+
.replace(/[\r\n]+/g, '')
32+
);
33+
};
34+
535
/**
636
* Groups all the API metadata nodes by module (`api` property) so that we can process each different file
737
* based on the module it belongs to.

‎packages/react/src/html/ui/components/DocumentationIndex/index.jsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import { STABILITY_KINDS, STABILITY_LABELS } from '../constants.mjs';
88
* @property {string} api - Basename of the document, linked as `${api}.html`
99
* @property {string} name - Human-readable name from the document's heading
1010
* @property {string} index - Stability index (e.g. `'2'` or `'1.1'`)
11+
* @property {string} [description] - The document's `llm_description`, or its first paragraph
1112
*/
1213

1314
/**

‎packages/react/src/jsx-ast/generate.mjs‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
import getConfig from '@doc-kit/core/utils/configuration/index.mjs';
2-
import { groupNodesByModule } from '@doc-kit/core/utils/generators.mjs';
2+
import {
3+
getEntryDescription,
4+
groupNodesByModule,
5+
} from '@doc-kit/core/utils/generators.mjs';
36
import { jsx, toJs } from 'estree-util-to-js';
47

58
import { DOCUMENTATION_INDEX_TAG } from './constants.mjs';
@@ -20,11 +23,11 @@ const buildDocumentationIndex = moduleEntries =>
2023
inline: false,
2124
entries: getSortedHeadNodes(moduleEntries)
2225
.filter(entry => entry.stability)
23-
.map(({ api, heading, stability, llm_description }) => ({
24-
api,
25-
name: heading.data.name,
26-
index: stability.data.index,
27-
description: llm_description,
26+
.map(entry => ({
27+
api: entry.api,
28+
name: entry.heading.data.name,
29+
index: entry.stability.data.index,
30+
description: getEntryDescription(entry),
2831
})),
2932
});
3033

‎packages/react/src/llms-txt/utils/__tests__/buildApiDocLink.test.mjs‎

Lines changed: 1 addition & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,7 @@
11
import assert from 'node:assert/strict';
22
import { describe, it } from 'node:test';
33

4-
import { getEntryDescription, buildApiDocLink } from '../buildApiDocLink.mjs';
5-
6-
describe('getEntryDescription', () => {
7-
it('returns llm_description when available', () => {
8-
const entry = {
9-
llm_description: 'LLM generated description',
10-
content: { children: [] },
11-
};
12-
13-
const result = getEntryDescription(entry);
14-
assert.equal(result, 'LLM generated description');
15-
});
16-
17-
it('extracts first paragraph when no llm_description', () => {
18-
const entry = {
19-
content: {
20-
children: [
21-
{
22-
type: 'paragraph',
23-
children: [{ type: 'text', value: 'First paragraph' }],
24-
},
25-
],
26-
},
27-
};
28-
29-
const result = getEntryDescription(entry);
30-
assert.ok(result.length > 0);
31-
});
32-
33-
it('returns empty string when no paragraph found', () => {
34-
const entry = {
35-
content: {
36-
children: [
37-
{ type: 'heading', children: [{ type: 'text', value: 'Title' }] },
38-
],
39-
},
40-
};
41-
42-
const result = getEntryDescription(entry);
43-
assert.equal(result, '');
44-
});
45-
46-
it('removes newlines from description', () => {
47-
const entry = {
48-
content: {
49-
children: [
50-
{
51-
type: 'paragraph',
52-
children: [{ type: 'text', value: 'Line 1\nLine 2\r\nLine 3' }],
53-
},
54-
],
55-
},
56-
};
57-
58-
const result = getEntryDescription(entry);
59-
assert.equal(result.includes('\n'), false);
60-
assert.equal(result.includes('\r'), false);
61-
});
62-
});
4+
import { buildApiDocLink } from '../buildApiDocLink.mjs';
635

646
describe('buildApiDocLink', () => {
657
it('builds markdown link with description', () => {

‎packages/react/src/llms-txt/utils/buildApiDocLink.mjs‎

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,5 @@
11
import { populate } from '@doc-kit/core/utils/configuration/templates.mjs';
2-
import { transformNodeToString } from '@doc-kit/core/utils/unist.mjs';
3-
4-
/**
5-
* Retrieves the description of a given API doc entry. It first checks whether
6-
* the entry has a llm_description property. If not, it extracts the first
7-
* paragraph from the entry's content.
8-
*
9-
* @param {import('@doc-kit/core/generators/metadata/types').MetadataEntry} entry
10-
* @returns {string}
11-
*/
12-
export const getEntryDescription = entry => {
13-
if (entry.llm_description) {
14-
return entry.llm_description.trim();
15-
}
16-
17-
const descriptionNode = entry.content.children.find(
18-
child => child.type === 'paragraph'
19-
);
20-
21-
if (!descriptionNode) {
22-
return '';
23-
}
24-
25-
return (
26-
transformNodeToString(descriptionNode)
27-
// Remove newlines and extra spaces
28-
.replace(/[\r\n]+/g, '')
29-
);
30-
};
2+
import { getEntryDescription } from '@doc-kit/core/utils/generators.mjs';
313

324
/**
335
* Builds a markdown link for an API doc entry

0 commit comments

Comments
 (0)