docs: update docusaurus to v3 (#5625)

* update dependencies

* update onboarding mdx

* fixes for mdx issues

* fixes for mdx compatibility

* resolve mdx errors

* fixes in reference

* fix check errors

* revert change in vale action

* fix node version in action

* fix summary in markdown
This commit is contained in:
Shahed Nasser
2023-11-13 20:11:50 +02:00
committed by GitHub
parent cedab58339
commit c6dff873de
2265 changed files with 46163 additions and 47195 deletions

View File

@@ -20,6 +20,12 @@ module.exports = {
sections: {
member_sources_definedIn: false,
reflection_hierarchy: false,
member_sources_inheritedFrom: false,
member_sources_implementationOf: false,
reflection_implementedBy: false,
member_signature_sources: false,
reflection_callable: false,
reflection_indexable: false,
},
parameterStyle: "component",
parameterComponent: "ParameterTypes",

View File

@@ -14,6 +14,10 @@ const defaultFormattingOptions = {
member_signature_title: false,
member_signature_returns: false,
title_reflectionPath: false,
reflection_callable: false,
reflection_indexable: false,
reflection_implementedBy: false,
member_declaration_title: false,
},
parameterStyle: "component",
parameterComponent: "ParameterTypes",

View File

@@ -3,6 +3,7 @@ import * as Handlebars from "handlebars"
import * as Path from "path"
import { CommentDisplayPart } from "typedoc/dist/lib/models/comments/comment"
import { MarkdownTheme } from "../../theme"
import { escapeChars } from "../../utils"
export default function (theme: MarkdownTheme) {
Handlebars.registerHelper("comment", function (parts: CommentDisplayPart[]) {
@@ -10,6 +11,8 @@ export default function (theme: MarkdownTheme) {
for (const part of parts) {
switch (part.kind) {
case "text":
result.push(escapeChars(part.text, false))
break
case "code":
result.push(part.text)
break

View File

@@ -31,7 +31,8 @@ export default function (theme: MarkdownTheme) {
(reflection.parent?.kindOf(ReflectionKind.Enum) ? " = " : ": ") +
Handlebars.helpers.type.call(
reflectionType ? reflectionType : reflection,
"object"
"object",
false
)
)
}
@@ -43,11 +44,7 @@ export default function (theme: MarkdownTheme) {
`${this.flags.isRest ? "... " : ""} **${escapeChars(this.name)}**`
)
if (this instanceof DeclarationReflection && this.typeParameters) {
md.push(
`<${this.typeParameters
.map((typeParameter) => `\`${typeParameter.name}\``)
.join(", ")}\\>`
)
md.push(`\`<${this.typeParameters.join(", ")}>\``)
}
md.push(getType(this))

View File

@@ -28,7 +28,7 @@ export default function (theme: MarkdownTheme) {
const typeParameters = this.model.typeParameters
.map((typeParameter: ParameterReflection) => typeParameter.name)
.join(", ")
title.push(`<${typeParameters}${shouldEscape ? "\\>" : ">"}`)
title.push(`\`<${typeParameters}>\``)
}
}
if (reflectionTitle?.suffix) {

View File

@@ -4,7 +4,7 @@ import {
ReflectionKind,
SignatureReflection,
} from "typedoc"
import { memberSymbol } from "../../utils"
import { getHTMLChar, memberSymbol } from "../../utils"
import { MarkdownTheme } from "../../theme"
export default function (theme: MarkdownTheme) {
@@ -21,30 +21,23 @@ export default function (theme: MarkdownTheme) {
}
const md: string[] = []
if (!expandMembers) {
md.push("`")
}
if (standalone && !theme.hideMembersSymbol) {
md.push(`${memberSymbol(this)} `)
}
if (this.parent && this.parent.flags?.length > 0) {
md.push(
this.parent.flags
.map(
(flag) =>
`${!expandMembers ? "`" : ""}${flag}${
!expandMembers ? "`" : ""
}`
)
.join(" ") + " "
)
md.push(this.parent.flags.join(" ") + " ")
}
if (accessor) {
md.push(
`${!expandMembers ? "`" : ""}${accessor}${
!expandMembers ? "`" : ""
} ${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
this.name
}${!expandMembers ? "**" : ""}`
`${accessor}${
expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"
}${this.name}${!expandMembers ? "**" : ""}`
)
} else if (this.name !== "__call" && this.name !== "__type") {
md.push(
@@ -56,22 +49,19 @@ export default function (theme: MarkdownTheme) {
if (this.typeParameters) {
md.push(
`<${this.typeParameters
.map(
(typeParameter) =>
`${!expandMembers ? "`" : ""}${typeParameter.name}${
!expandMembers ? "`" : ""
}`
)
.join(", ")}\\>`
`${expandMembers ? getHTMLChar("<") : "<"}${this.typeParameters.join(
", "
)}${expandMembers ? getHTMLChar(">") : ">"}`
)
}
md.push(`(${getParameters(this.parameters, !expandMembers)})`)
md.push(`(${getParameters(this.parameters, false)})`)
if (this.type && !this.parent?.kindOf(ReflectionKind.Constructor)) {
md.push(
`: ${Handlebars.helpers.type.call(this.type, "none", !expandMembers)}`
)
md.push(`: ${Handlebars.helpers.type.call(this.type, "none", false)}`)
}
if (!expandMembers) {
md.push("`")
}
return md.join("") + (standalone ? "\n" : "")
}

View File

@@ -4,7 +4,7 @@
{{#if hasVisibleComponent}}
{{{comments this}}}
{{{comments this true true 4 model}}}
{{/if}}

View File

@@ -1,10 +1,18 @@
{{#if (sectionEnabled "member_declaration_title")}}
{{{declarationTitle}}}
{{/if}}
{{#if (sectionEnabled "member_declaration_comment")}}
{{> comment}}
{{/if}}
{{#if (sectionEnabled "member_declaration_example")}}
{{{example this 4}}}
{{{example this 3}}}
{{/if}}
@@ -12,7 +20,7 @@
{{#if typeParameters}}
{{titleLevel 4}} Type parameters
{{titleLevel 3}} Type parameters
{{#with typeParameters}}
@@ -32,7 +40,7 @@
{{#with type.declaration.indexSignature}}
{{titleLevel 4}} Index signature
{{titleLevel 3}} Index signature
{{{indexSignatureTitle}}}
@@ -50,11 +58,11 @@
{{#if type.declaration.children}}
{{titleLevel 4}} Call signature
{{titleLevel 3}} Call signature
{{else}}
{{titleLevel 4}} Type declaration
{{titleLevel 3}} Type declaration
{{/if}}
@@ -74,7 +82,7 @@
{{#with type.declaration}}
{{titleLevel 4}} Type declaration
{{titleLevel 3}} Type declaration
{{/with}}

View File

@@ -19,6 +19,9 @@ export type ObjectLiteralDeclarationStyle = "table" | "list" | "component"
export type SectionKey =
| "comment"
| "member_declaration"
| "member_declaration_title"
| "member_declaration_comment"
| "member_declaration_typeParameters"
| "member_declaration_indexSignature"
| "member_declaration_signatures"
@@ -29,7 +32,6 @@ export type SectionKey =
| "member_signatures"
| "member_getterSetter"
| "member_reference"
| "member_declaration"
| "member_signature_title"
| "member_signature_comment"
| "member_signature_typeParameters"

View File

@@ -16,13 +16,17 @@ export function formatContents(contents: string) {
)
}
export function escapeChars(str: string) {
export function getHTMLChar(str: string) {
return str
.replace(/>/g, "\\>")
.replace(/>/g, "\\>")
.replace(/_/g, "\\_")
.replace(/`/g, "\\`")
.replace(/\|/g, "\\|")
.replace(/</g, "&#60;")
.replace(/{/g, "&#123;")
.replace(/}/g, "&#125;")
.replace(/>/g, "&#62;")
}
export function escapeChars(str: string, escapeBackticks = true) {
const result = getHTMLChar(str).replace(/_/g, "\\_").replace(/\|/g, "\\|")
return escapeBackticks ? result.replace(/`/g, "\\`") : result
}
export function memberSymbol(

View File

@@ -1,4 +1,9 @@
import { Comment, ReflectionKind, ReflectionType } from "typedoc"
import {
Comment,
DeclarationReflection,
ReflectionKind,
ReflectionType,
} from "typedoc"
import * as Handlebars from "handlebars"
import { stripCode, stripLineBreaks } from "../utils"
import { Parameter, ParameterStyle, ReflectionParameterType } from "../types"
@@ -72,7 +77,7 @@ export function reflectionListFormatter(
: getTypeChildren(reflection.type!, reflection.project)
const itemChildren: string[] = []
let itemChildrenKind: ReflectionKind | null = null
children?.forEach((childItem) => {
children?.forEach((childItem: DeclarationReflection) => {
if (!itemChildrenKind) {
itemChildrenKind = childItem.kind
}
@@ -102,7 +107,7 @@ export function reflectionComponentFormatter(
name: reflection.name,
type: reflection.type
? getType(reflection.type, "object")
: getReflectionType(reflection, "object"),
: getReflectionType(reflection, "object", true),
description: comments
? stripLineBreaks(Handlebars.helpers.comments(comments, true, false))
: "",
@@ -124,8 +129,10 @@ export function reflectionComponentFormatter(
: getTypeChildren(reflection.type!, reflection.project)
children
?.filter((childItem) => childItem.kindOf(ALLOWED_KINDS))
.forEach((childItem) => {
?.filter((childItem: DeclarationReflection) =>
childItem.kindOf(ALLOWED_KINDS)
)
.forEach((childItem: DeclarationReflection) => {
componentItem.children?.push(
reflectionComponentFormatter(childItem, level + 1, maxLevel)
)
@@ -163,7 +170,7 @@ export function reflectionTableFormatter(
row.push(
parameter.type
? Handlebars.helpers.type.call(parameter.type, "object")
: getReflectionType(parameter, "object")
: getReflectionType(parameter, "object", true)
)
if (showDefaults) {

View File

@@ -21,7 +21,7 @@ export function returnReflectionComponentFormatter(
level = 1,
maxLevel?: number | undefined
): Parameter[] {
const typeName = getType(reflectionType, "object", false)
const typeName = getType(reflectionType, "object", false, true)
const type = getType(reflectionType, "object")
const componentItem: Parameter[] = []
if (reflectionType.type === "reference") {

View File

@@ -20,33 +20,34 @@ import {
} from "typedoc"
import * as Handlebars from "handlebars"
import { ReflectionParameterType } from "../types"
import { escapeChars } from "../utils"
import { escapeChars, getHTMLChar } from "../utils"
export type Collapse = "object" | "function" | "all" | "none"
export default function getType(
reflectionType: SomeType,
collapse: Collapse = "none",
emphasis = true
emphasis = true,
hideLink = false
): string {
if (reflectionType instanceof ReferenceType) {
return getReferenceType(reflectionType, emphasis)
return getReferenceType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof ArrayType && reflectionType.elementType) {
return getArrayType(reflectionType, emphasis)
return getArrayType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof UnionType && reflectionType.types) {
return getUnionType(reflectionType, emphasis)
return getUnionType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof IntersectionType && reflectionType.types) {
return getIntersectionType(reflectionType)
return getIntersectionType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof TupleType && reflectionType.elements) {
return getTupleType(reflectionType)
return getTupleType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof IntrinsicType && reflectionType.name) {
@@ -54,27 +55,32 @@ export default function getType(
}
if (reflectionType instanceof ReflectionType) {
return getReflectionType(reflectionType.declaration, collapse)
return getReflectionType(
reflectionType.declaration,
collapse,
emphasis,
hideLink
)
}
if (reflectionType instanceof DeclarationReflection) {
return getReflectionType(reflectionType, collapse)
return getReflectionType(reflectionType, collapse, emphasis, hideLink)
}
if (reflectionType instanceof TypeOperatorType) {
return getTypeOperatorType(reflectionType)
return getTypeOperatorType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof QueryType) {
return getQueryType(reflectionType)
return getQueryType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof ConditionalType) {
return getConditionalType(reflectionType)
return getConditionalType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof IndexedAccessType) {
return getIndexAccessType(reflectionType)
return getIndexAccessType(reflectionType, emphasis, hideLink)
}
if (reflectionType instanceof UnknownType) {
@@ -86,7 +92,7 @@ export default function getType(
}
if (reflectionType instanceof LiteralType) {
return getLiteralType(reflectionType)
return getLiteralType(reflectionType, emphasis)
}
return reflectionType ? escapeChars(reflectionType.toString()) : ""
@@ -94,148 +100,203 @@ export default function getType(
export function getReflectionType(
model: ReflectionParameterType,
collapse: Collapse
collapse: Collapse,
emphasis: boolean,
hideLink = false
): string {
if ("signatures" in model && model.signatures) {
return collapse === "function" || collapse === "all"
? `\`fn\``
: getFunctionType(model.signatures)
? `${emphasis ? "`" : ""}fn${emphasis ? "`" : ""}`
: getFunctionType(model.signatures, emphasis, hideLink)
}
return collapse === "object" || collapse === "all"
? `\`object\``
: getDeclarationType(model as DeclarationReflection)
? `${emphasis ? "`" : ""}object${emphasis ? "`" : ""}`
: `${emphasis ? "`" : ""}${getDeclarationType(
model as DeclarationReflection,
false,
hideLink
)}${emphasis ? "`" : ""}`
}
export function getDeclarationType(model: DeclarationReflection): string {
export function getDeclarationType(
model: DeclarationReflection,
emphasis: boolean,
hideLink = false
): string {
if (model.indexSignature || model.children) {
let indexSignature = ""
const declarationIndexSignature = model.indexSignature
if (declarationIndexSignature) {
const key = declarationIndexSignature.parameters
? declarationIndexSignature.parameters.map(
(param) => `\`[${param.name}: ${param.type}]\``
(param) => `[${param.name}: ${param.type}]`
)
: ""
const obj = declarationIndexSignature.type
? getType(declarationIndexSignature.type)
? getType(declarationIndexSignature.type, "none", false, hideLink)
: ""
indexSignature = `${key}: ${obj}; `
}
const types =
model.children &&
model.children.map((obj) => {
return `\`${obj.name}${obj.flags.isOptional ? "?" : ""}\`: ${
obj.type ? getType(obj.type) : escapeChars(obj.toString())
return `${obj.name}${obj.flags.isOptional ? "?" : ""}: ${
obj.type
? getType(obj.type, "none", false, hideLink)
: escapeChars(obj.toString())
} ${
obj.defaultValue && obj.defaultValue !== "..."
? `= ${escapeChars(`${obj.defaultValue}`)}`
: ""
}`
})
return `{ ${indexSignature ? indexSignature : ""}${
types ? types.join("; ") : ""
} }${
return `${emphasis ? "`{" : getHTMLChar("{")} ${
indexSignature ? indexSignature : ""
}${types ? types.join("; ") : ""} ${emphasis ? "}`" : getHTMLChar("}")}${
model.defaultValue && model.defaultValue !== "..."
? `= ${escapeChars(`${model.defaultValue}`)}`
: ""
}`
}
return "{}"
return emphasis ? "`{}`" : escapeChars("{}")
}
export function getFunctionType(
modelSignatures: SignatureReflection[]
modelSignatures: SignatureReflection[],
emphasis: boolean,
hideLink = false
): string {
const functions = modelSignatures.map((fn) => {
const typeParams = fn.typeParameters
? `<${fn.typeParameters
? `${emphasis ? "`<" : getHTMLChar("<")}${fn.typeParameters
.map((typeParameter) => typeParameter.name)
.join(", ")}\\>`
.join(", ")}${emphasis ? ">`" : getHTMLChar(">")}`
: []
const params = fn.parameters
? fn.parameters.map((param) => {
return `${param.flags.isRest ? "..." : ""}\`${param.name}${
param.flags.isOptional ? "?" : ""
}\`: ${
param.type ? getType(param.type) : escapeChars(param.toString())
return `${param.flags.isRest ? "..." : ""}${emphasis ? "`" : ""}${
param.name
}${param.flags.isOptional ? "?" : ""}${emphasis ? "`" : ""}: ${
param.type
? getType(param.type, "none", emphasis, hideLink)
: escapeChars(param.toString())
}`
})
: []
const returns = fn.type ? getType(fn.type) : escapeChars(fn.toString())
const returns = fn.type
? getType(fn.type, "none", emphasis, hideLink)
: escapeChars(fn.toString())
return typeParams + `(${params.join(", ")}) => ${returns}`
})
return functions.join("")
}
export function getLiteralType(model: LiteralType): string {
export function getLiteralType(model: LiteralType, emphasis: boolean): string {
if (typeof model.value === "bigint") {
return `\`${model.value}n\``
return `${emphasis ? "`" : ""}${model.value}n${emphasis ? "`" : ""}`
}
return `\`\`${JSON.stringify(model.value)}\`\``
return `${emphasis ? "`" : ""}\`${JSON.stringify(model.value)}\`${
emphasis ? "`" : ""
}`
}
export function getReferenceType(
model: ReferenceType,
emphasis: boolean
emphasis: boolean,
hideLink = false
): string {
const shouldShowLink = emphasis && model.name !== "Record"
const shouldShowLink = !hideLink && model.name !== "Record"
const wrappingBackticks = emphasis && !shouldShowLink
if (model.reflection || (model.name && model.typeArguments)) {
const reflection: string[] = []
const reflection: string[] = [wrappingBackticks ? "`" : ""]
if (model.reflection?.url) {
reflection.push(
shouldShowLink
? `[${`\`${model.reflection.name}\``}](${Handlebars.helpers.relativeURL(
? `[${model.reflection.name}](${Handlebars.helpers.relativeURL(
model.reflection.url
)})`
: model.reflection.name
: emphasis
? model.reflection.name
: escapeChars(model.reflection.name)
)
} else {
reflection.push(
shouldShowLink
? model.externalUrl
? `[${`\`${model.name}\``}]( ${model.externalUrl} )`
: `\`${model.name}\``
: model.name
? `[${model.name}]( ${model.externalUrl} )`
: model.name
: emphasis
? model.name
: escapeChars(model.name)
)
}
if (model.typeArguments && model.typeArguments.length > 0) {
reflection.push(
`<${model.typeArguments
.map((typeArgument) => getType(typeArgument, "none", emphasis))
.join(", ")}\\>`
`${wrappingBackticks ? "<" : getHTMLChar("<")}${model.typeArguments
.map((typeArgument) => getType(typeArgument, "none", false, hideLink))
.join(", ")}${wrappingBackticks ? ">" : getHTMLChar(">")}`
)
}
if (wrappingBackticks) {
reflection.push("`")
}
return reflection.join("")
}
return shouldShowLink
? model.externalUrl
? `[${`\`${model.name}\``}]( ${model.externalUrl} )`
: `\`${model.name}\``
? `[${emphasis ? `\`${model.name}\`` : escapeChars(model.name)}]( ${
model.externalUrl
} )`
: emphasis
? `\`${model.name}\``
: escapeChars(model.name)
: emphasis
? `\`${model.name}\``
: escapeChars(model.name)
}
export function getArrayType(model: ArrayType, emphasis: boolean): string {
const arrayType = getType(model.elementType, "none", emphasis)
export function getArrayType(
model: ArrayType,
emphasis: boolean,
hideLink = false
): string {
const arrayType = getType(model.elementType, "none", emphasis, hideLink)
return model.elementType.type === "union"
? `(${arrayType})[]`
: `${arrayType}[]`
}
export function getUnionType(model: UnionType, emphasis: boolean): string {
export function getUnionType(
model: UnionType,
emphasis: boolean,
hideLink = false
): string {
return model.types
.map((unionType) => getType(unionType, "none", emphasis))
.map((unionType) => getType(unionType, "none", emphasis, hideLink))
.join(` \\| `)
}
export function getIntersectionType(model: IntersectionType): string {
export function getIntersectionType(
model: IntersectionType,
emphasis: boolean,
hideLink = false
): string {
return model.types
.map((intersectionType) => getType(intersectionType))
.map((intersectionType) =>
getType(intersectionType, "none", emphasis, hideLink)
)
.join(" & ")
}
export function getTupleType(model: TupleType): string {
return `[${model.elements.map((element) => getType(element)).join(", ")}]`
export function getTupleType(
model: TupleType,
emphasis: boolean,
hideLink = false
): string {
return `[${model.elements
.map((element) => getType(element, "none", emphasis, hideLink))
.join(", ")}]`
}
export function getIntrinsicType(
@@ -245,12 +306,25 @@ export function getIntrinsicType(
return emphasis ? `\`${model.name}\`` : escapeChars(model.name)
}
export function getTypeOperatorType(model: TypeOperatorType): string {
return `${model.operator} ${getType(model.target)}`
export function getTypeOperatorType(
model: TypeOperatorType,
emphasis: boolean,
hideLink = false
): string {
return `${model.operator} ${getType(
model.target,
"none",
emphasis,
hideLink
)}`
}
export function getQueryType(model: QueryType): string {
return `typeof ${getType(model.queryType)}`
export function getQueryType(
model: QueryType,
emphasis: boolean,
hideLink = false
): string {
return `typeof ${getType(model.queryType, "none", emphasis, hideLink)}`
}
export function getInferredType(model: InferredType): string {
@@ -261,33 +335,41 @@ export function getUnknownType(model: UnknownType): string {
return escapeChars(model.name)
}
export function getConditionalType(model: ConditionalType): string {
export function getConditionalType(
model: ConditionalType,
emphasis: boolean,
hideLink = false
): string {
const md: string[] = []
if (model.checkType) {
md.push(getType(model.checkType))
md.push(getType(model.checkType, "none", emphasis, hideLink))
}
md.push("extends")
if (model.extendsType) {
md.push(getType(model.extendsType))
md.push(getType(model.extendsType, "none", emphasis, hideLink))
}
md.push("?")
if (model.trueType) {
md.push(getType(model.trueType))
md.push(getType(model.trueType, "none", emphasis, hideLink))
}
md.push(":")
if (model.falseType) {
md.push(getType(model.falseType))
md.push(getType(model.falseType, "none", emphasis, hideLink))
}
return md.join(" ")
}
export function getIndexAccessType(model: IndexedAccessType): string {
export function getIndexAccessType(
model: IndexedAccessType,
emphasis: boolean,
hideLink = false
): string {
const md: string[] = []
if (model.objectType) {
md.push(getType(model.objectType))
md.push(getType(model.objectType, "none", emphasis, hideLink))
}
if (model.indexType) {
md.push(`[${getType(model.indexType)}]`)
md.push(`[${getType(model.indexType, "none", false, hideLink)}]`)
}
return md.join("")
}