Nomchy/discord.js
1
0
Fork 0
mirror of https://github.com/discordjs/discord.js.git synced 2026-03-09 16:13:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

refactor: docs (#10126)

Browse Source
This commit is contained in:
Noel
2024-02-29 04:37:52 +01:00
committed by GitHub
parent 0f9017ef95
commit 18cce83d80
192 changed files with 8116 additions and 6321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
packages/scripts/src/generateSplitDocumentation.ts
View File

@@ -35,6 +35,7 @@ import {
ApiStaticMixin,
ExcerptTokenKind,
ExcerptToken,
ApiOptionalMixin,
} from '@discordjs/api-extractor-model';
import { DocNodeKind, SelectorKind, StandardTags } from '@microsoft/tsdoc';
import type {
@@ -276,7 +277,7 @@ function itemExcerptText(excerpt: Excerpt, apiPackage: ApiPackage) {
}
return {
text: token.text,
text: token.text.replace(/import\("discord-api-types(?:\/v\d+)?"\)\./, ''),
};
});
}
@@ -304,19 +305,19 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
const { codeDestination, urlDestination, linkText } = node as DocLinkTag;
if (codeDestination) {
if (
!codeDestination.importPath &&
!codeDestination.packageName &&
codeDestination.memberReferences.length === 1 &&
codeDestination.memberReferences[0]!.memberIdentifier
) {
const typeName = codeDestination.memberReferences[0]!.memberIdentifier.identifier;
// if (
// !codeDestination.importPath &&
// !codeDestination.packageName &&
// codeDestination.memberReferences.length === 1 &&
// codeDestination.memberReferences[0]!.memberIdentifier
// ) {
// const typeName = codeDestination.memberReferences[0]!.memberIdentifier.identifier;
return {
kind: DocNodeKind.LinkTag,
text: typeName,
};
}
// return {
// kind: DocNodeKind.LinkTag,
// text: typeName,
// };
// }
const declarationReference = apiItem
.getAssociatedModel()
@@ -359,7 +360,7 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
text: linkText ?? foundItem?.displayName ?? resolved!.item.displayName,
uri: resolveItemURI(foundItem ?? resolved!.item),
resolvedPackage: {
packageName: resolved?.package ?? apiItem.getAssociatedPackage()?.displayName,
packageName: resolved?.package ?? apiItem.getAssociatedPackage()?.displayName.replace('@discordjs/', ''),
version: resolved?.package
? apiItem.getAssociatedPackage()?.dependencies?.[resolved.package] ?? null
: null,
@@ -413,13 +414,37 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
return {
kind: DocNodeKind.Comment,
deprecatedBlock: comment.deprecatedBlock ? createNode(comment.deprecatedBlock.content) : null,
summarySection: comment.summarySection ? createNode(comment.summarySection) : null,
remarksBlock: comment.remarksBlock ? createNode(comment.remarksBlock.content) : null,
defaultValueBlock: defaultValueBlock ? createNode(defaultValueBlock.content) : null,
returnsBlock: comment.returnsBlock ? createNode(comment.returnsBlock.content) : null,
exampleBlocks: exampleBlocks.map((block) => createNode(block.content)),
seeBlocks: comment.seeBlocks.map((block) => createNode(block.content)),
deprecatedBlock: comment.deprecatedBlock
? createNode(comment.deprecatedBlock.content)
.flat(1)
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
: [],
summarySection: comment.summarySection
? createNode(comment.summarySection)
.flat(1)
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
: [],
remarksBlock: comment.remarksBlock
? createNode(comment.remarksBlock.content)
.flat(1)
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
: [],
defaultValueBlock: defaultValueBlock
? createNode(defaultValueBlock.content)
.flat(1)
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
: [],
returnsBlock: comment.returnsBlock
? createNode(comment.returnsBlock.content)
.flat(1)
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
: [],
exampleBlocks: exampleBlocks
.flatMap((block) => createNode(block.content).flat(1))
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak),
seeBlocks: comment.seeBlocks
.flatMap((block) => createNode(block.content).flat(1))
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak),
};
}
@@ -429,7 +454,9 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
};
return item.kind === DocNodeKind.Paragraph || item.kind === DocNodeKind.Section
? (item as DocNodeContainer).nodes.flatMap((node) => createNode(node))
? (item as DocNodeContainer).nodes
.flatMap((node) => createNode(node))
.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
: createNode(item);
}
@@ -440,6 +467,7 @@ function itemInfo(item: ApiDeclaredItem) {
const isProtected = ApiProtectedMixin.isBaseClassOf(item) && item.isProtected;
const isReadonly = ApiReadonlyMixin.isBaseClassOf(item) && item.isReadonly;
const isAbstract = ApiAbstractMixin.isBaseClassOf(item) && item.isAbstract;
const isOptional = ApiOptionalMixin.isBaseClassOf(item) && item.isOptional;
const isDeprecated = Boolean(item.tsdocComment?.deprecatedBlock);
const hasSummary = Boolean(item.tsdocComment?.summarySection);
@@ -450,12 +478,13 @@ function itemInfo(item: ApiDeclaredItem) {
sourceURL: item.sourceLocation.fileUrl,
sourceLine: item.sourceLocation.fileLine,
sourceExcerpt,
summary: hasSummary ? itemTsDoc(item.tsdocComment!.summarySection!, item) : null,
summary: hasSummary ? itemTsDoc(item.tsdocComment!, item) : null,
isStatic,
isProtected,
isReadonly,
isAbstract,
isDeprecated,
isOptional,
};
}
@@ -505,7 +534,7 @@ function itemTypeParameters(item: ApiTypeParameterListMixin) {
return item.typeParameters.map((typeParam) => ({
name: typeParam.name,
constraintsExcerpt: itemExcerptText(typeParam.constraintExcerpt, item.getAssociatedPackage()!),
optional: typeParam.isOptional,
isOptional: typeParam.isOptional,
defaultExcerpt: itemExcerptText(typeParam.defaultTypeExcerpt, item.getAssociatedPackage()!),
description: typeParam.tsdocTypeParamBlock ? itemTsDoc(typeParam.tsdocTypeParamBlock.content, item) : null,
}));
@@ -524,7 +553,7 @@ function itemParameters(item: ApiDocumentedItem & ApiParameterListMixin) {
return params.map((param) => ({
name: param.isRest ? `...${param.name}` : param.name,
typeExcerpt: itemExcerptText(param.parameterTypeExcerpt, item.getAssociatedPackage()!),
optional: param.isOptional,
isOptional: param.isOptional,
description: param.description ? itemTsDoc(param.description, item) : null,
}));
}
@@ -535,6 +564,7 @@ function itemConstructor(item: ApiConstructor) {
name: item.displayName,
sourceURL: item.sourceLocation.fileUrl,
sourceLine: item.sourceLocation.fileLine,
parametersString: parametersString(item),
summary: item.tsdocComment ? itemTsDoc(item.tsdocComment, item) : null,
parameters: itemParameters(item),
};
@@ -552,7 +582,7 @@ function itemEvent(item: ApiItemContainerMixin) {
return {
...itemInfo(event.item),
inheritedFrom: event.inherited?.displayName,
inheritedFrom: event.inherited ? resolveItemURI(event.inherited) : null,
summary: hasSummary ? itemTsDoc(event.item.tsdocComment!, event.item) : null,
parameters: itemParameters(event.item),
};
@@ -571,7 +601,7 @@ function itemProperty(item: ApiItemContainerMixin) {
return {
...itemInfo(property.item),
inheritedFrom: property.inherited?.displayName,
inheritedFrom: property.inherited ? resolveItemURI(property.inherited) : null,
typeExcerpt: itemExcerptText(property.item.propertyTypeExcerpt, property.item.getAssociatedPackage()!),
summary: hasSummary ? itemTsDoc(property.item.tsdocComment!, property.item) : null,
};
@@ -598,24 +628,40 @@ function isMethodLike(item: ApiItem): item is ApiMethod | ApiMethodSignature {
function itemMethod(item: ApiItemContainerMixin) {
const members = resolveMembers(item, isMethodLike);
return members.map((method) => {
const parent = method.item.parent as ApiDeclaredItem;
const firstOverload = method.item
.getMergedSiblings()
.find(
(meth): meth is ApiMethod => meth.kind === ApiItemKind.Method && (meth as ApiMethod).overloadIndex === 1,
)?.tsdocComment;
const hasSummary = Boolean(method.item.tsdocComment?.summarySection ?? firstOverload?.summarySection);
const methodItem = (method: {
inherited?: ApiItemContainerMixin | undefined;
item: ApiMethod | ApiMethodSignature;
}) => {
const hasSummary = Boolean(method.item.tsdocComment?.summarySection);
return {
...itemInfo(method.item),
overloadIndex: method.item.overloadIndex,
parametersString: parametersString(method.item),
returnTypeExcerpt: itemExcerptText(method.item.returnTypeExcerpt, method.item.getAssociatedPackage()!),
inheritedFrom: parent ? method.inherited?.displayName : null,
inheritedFrom: method.inherited ? resolveItemURI(method.inherited) : null,
typeParameters: itemTypeParameters(method.item),
parameters: itemParameters(method.item),
summary: hasSummary ? itemTsDoc(method.item.tsdocComment ?? firstOverload!, method.item) : null,
summary: hasSummary ? itemTsDoc(method.item.tsdocComment!, method.item) : null,
};
};
return members.map((method) => {
// const parent = method.item.parent as ApiDeclaredItem;
const hasOverload =
method.item
.getMergedSiblings()
.filter((sibling) => sibling.kind === ApiItemKind.Method || sibling.kind === ApiItemKind.MethodSignature)
.length > 1;
const overloads = method.item
.getMergedSiblings()
.filter((sibling) => sibling.kind === ApiItemKind.Method || sibling.kind === ApiItemKind.MethodSignature)
.map((sibling) => methodItem({ item: sibling as ApiMethod | ApiMethodSignature }));
return {
...methodItem(method),
overloads: hasOverload ? overloads : [],
};
});
}
@@ -709,10 +755,21 @@ function itemClass(item: ApiClass) {
}
function itemFunction(item: ApiFunction) {
const functionItem = (item: ApiFunction) => {
return {
...itemInfo(item),
overloadIndex: item.overloadIndex,
typeParameters: itemTypeParameters(item),
parameters: itemParameters(item),
};
};
const hasOverloads = item.getMergedSiblings().length > 1;
const overloads = item.getMergedSiblings().map((sibling) => functionItem(sibling as ApiFunction));
return {
...itemInfo(item),
typeParameters: itemTypeParameters(item),
parameters: itemParameters(item),
...functionItem(item),
overloads: hasOverloads ? overloads : [],
};
}
@@ -769,6 +826,7 @@ function itemUnion(item: ApiTypeAlias) {
function itemTypeAlias(item: ApiTypeAlias) {
return {
...itemInfo(item),
typeParameters: itemTypeParameters(item),
unionMembers: itemUnion(item).map((member) =>
itemExcerptText(new Excerpt(member, { startIndex: 0, endIndex: member.length }), item.getAssociatedPackage()!),
),
@@ -835,17 +893,33 @@ function memberKind(member: ApiItem | null) {
}
}
async function writeSplitDocsToFileSystem(member: Record<string, any>, tag = 'main') {
async function writeSplitDocsToFileSystem({
member,
packageName,
tag = 'main',
overrideName,
}: {
member: Record<string, any>;
overrideName?: string;
packageName: string;
tag: string;
}) {
const dir = 'split';
try {
(await stat(join(cwd(), 'docs', dir))).isDirectory();
(await stat(join(cwd(), 'docs', packageName, dir))).isDirectory();
} catch {
await mkdir(join(cwd(), 'docs', dir));
await mkdir(join(cwd(), 'docs', packageName, dir), { recursive: true });
}
await writeFile(
join(cwd(), 'docs', dir, `${tag}.${member.displayName}.${member.kind}.api.json`),
join(
cwd(),
'docs',
packageName,
dir,
`${tag}.${overrideName ?? `${member.displayName.toLowerCase()}.${member.kind.toLowerCase()}`}.api.json`,
),
JSON.stringify(member),
);
}
@@ -868,14 +942,33 @@ export async function generateSplitDocumentation({
continue;
}
const members = entry.members.map((item) => ({
kind: item.kind,
name: item.displayName,
href: resolveItemURI(item),
overloadIndex: 'overloadIndex' in item ? (item.overloadIndex as number) : undefined,
}));
await writeSplitDocsToFileSystem({
member: pkg.dependencies ?? [],
packageName: pkgName,
tag: version,
overrideName: 'dependencies',
});
// await writeSplitDocsToFileSystem(members, version);
const members = entry.members
.filter((item) => {
if (item.kind !== 'Function') {
return true;
}
return (item as ApiFunction).overloadIndex === 1;
})
.map((item) => ({
kind: item.kind,
name: item.displayName,
href: resolveItemURI(item),
}));
await writeSplitDocsToFileSystem({
member: members,
packageName: pkgName,
tag: version,
overrideName: 'sitemap',
});
for (const member of members) {
const item = `${member.name}:${member.kind}`;
@@ -895,7 +988,7 @@ export async function generateSplitDocumentation({
continue;
}
await writeSplitDocsToFileSystem(returnValue, version);
await writeSplitDocsToFileSystem({ member: returnValue, packageName: pkgName, tag: version });
}
}
}