asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: fix tsdocs following typedoc update + 1.20 release (#6033)

Browse Source 
* docs: fix tsdocs following typedoc update + 1.20 release

* Fix OAS validation errors

* fixes to react-docs-generator

* fix content linting
This commit is contained in:
Shahed Nasser
2024-01-09 17:15:29 +02:00
committed by GitHub
parent 125879ada4
commit 18de90e603
32 changed files with 460 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs-util/packages/react-docs-generator/src/classes/typedoc-manager.ts
+54 -22
View File
@@ -6,7 +6,7 @@ import {
TSFunctionSignatureType,
TypeDescriptor,
} from "react-docgen/dist/Documentation.js"
import { Comment } from "typedoc"
import { Comment, ReferenceReflection, ReferenceType } from "typedoc"
import {
Application,
Context,
@@ -72,6 +72,8 @@ export default class TypedocManager {
tsconfig: this.options.tsconfigPath,
plugin: ["typedoc-plugin-custom"],
enableInternalResolve: true,
internalModule: "internal",
checkVariables: true,
logLevel: this.options.verbose ? "Verbose" : "None",
})
@@ -108,24 +110,35 @@ export default class TypedocManager {
// since the component may be a child of an exported component
// we use the reflectionPathName to retrieve the component
// by its "reflection path"
const reflection = this.project?.getChildByName(
reflectionPathName
) as DeclarationReflection
let reflection = this.project?.getChildByName(reflectionPathName) as
| DeclarationReflection
| ReferenceReflection
if (reflection && reflection instanceof ReferenceReflection) {
// load declaration reflection
reflection = reflection.getTargetReflection() as DeclarationReflection
}
if (!reflection) {
return spec
}
// retrieve the signature of the reflection
// this is helpful to retrieve the props of the component
const mappedSignature = reflection.sources?.length
? this.getMappedSignatureFromSource(reflection.sources[0])
: undefined
const doesReflectionHaveSignature =
reflection.type?.type === "reference" &&
reflection.type.reflection instanceof DeclarationReflection &&
reflection.type.reflection.signatures?.length
if (
mappedSignature?.signatures[0].parameters?.length &&
mappedSignature.signatures[0].parameters[0].type
) {
const signature = mappedSignature.signatures[0]
// If the original reflection in the reference type has a signature
// use that signature. Else, try to get the signature from the mapping.
const signature = doesReflectionHaveSignature
? (
(reflection.type! as ReferenceType)
.reflection as DeclarationReflection
).signatures![0]
: reflection.sources?.length
? this.getMappedSignatureFromSource(reflection.sources[0])
?.signatures[0]
: undefined
if (signature?.parameters?.length && signature.parameters[0].type) {
// get the props of the component from the
// first parameter in the signature.
const props = getTypeChildren({
@@ -212,7 +225,7 @@ export default class TypedocManager {
return
}
spec.props![prop.name] = {
description: this.normalizeDescription(this.getDescription(prop)),
description,
required: !prop.flags.isOptional,
tsType: prop.type
? this.getTsType(prop.type)
@@ -446,8 +459,9 @@ export default class TypedocManager {
// this is useful for the CustomResolver to check
// if a variable is a React component.
isReactComponent(name: string): boolean {
const reflection = this.getReflectionByName(name)
const reflection = this.getReflectionByName(name, {
hasSignature: true,
})
if (
!reflection ||
!(reflection instanceof DeclarationReflection) ||
@@ -459,7 +473,9 @@ export default class TypedocManager {
return reflection.signatures.some(
(signature) =>
signature.type?.type === "reference" &&
signature.type.name === "ReactNode"
(signature.type.name === "ReactNode" ||
(signature.type.name === "Element" &&
signature.type.package === "@types/react"))
)
}
@@ -571,11 +587,27 @@ export default class TypedocManager {
}
// Gets a reflection by its name.
getReflectionByName(name: string): DeclarationReflection | undefined {
getReflectionByName(
name: string,
options?: {
hasSignature?: boolean
}
): DeclarationReflection | undefined {
return this.project
? (Object.values(this.project?.reflections || {}).find(
(ref) => ref.name === name
) as DeclarationReflection)
? (Object.values(this.project?.reflections || {}).find((ref) => {
if (ref.name !== name) {
return false
}
if (
options?.hasSignature &&
(!(ref instanceof DeclarationReflection) || !ref.signatures)
) {
return false
}
return true
}) as DeclarationReflection)
: undefined
}
}
docs-util/packages/typedoc-config/extended-tsconfig/tsdoc.json
+4
View File
@@ -45,6 +45,10 @@
{
"tagName": "@typeParamDefinition",
"syntaxKind": "block"
},
{
"tagName": "@parentIgnore",
"syntaxKind": "block"
}
]
}
docs-util/packages/typedoc-config/fulfillment.js
+1
View File
@@ -5,4 +5,5 @@ module.exports = getConfig({
entryPointPath: "packages/medusa/src/interfaces/fulfillment-service.ts",
tsConfigName: "medusa.json",
name: "fulfillment",
parentIgnore: true,
})
docs-util/packages/typedoc-plugin-custom/src/index.ts
+2
View File
@@ -5,6 +5,7 @@ import { load as parseOasSchemaPlugin } from "./parse-oas-schema-plugin"
import { load as apiIgnorePlugin } from "./api-ignore"
import { load as eslintExamplePlugin } from "./eslint-example"
import { load as signatureModifierPlugin } from "./signature-modifier"
import { load as parentIgnorePlugin } from "./parent-ignore"
import { GenerateNamespacePlugin } from "./generate-namespace"
export function load(app: Application) {
@@ -14,6 +15,7 @@ export function load(app: Application) {
apiIgnorePlugin(app)
eslintExamplePlugin(app)
signatureModifierPlugin(app)
parentIgnorePlugin(app)
new GenerateNamespacePlugin(app)
}
docs-util/packages/typedoc-plugin-custom/src/parent-ignore.ts
+47
View File
@@ -0,0 +1,47 @@
import {
Application,
Context,
Converter,
DeclarationReflection,
ParameterType,
ReflectionKind,
} from "typedoc"
export function load(app: Application) {
app.options.addDeclaration({
name: "parentIgnore",
help: "Whether to ignore items with the `@parentIgnore` tag.",
type: ParameterType.Boolean, // The default
defaultValue: false,
})
app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => {
const isParentIgnoreEnabled = app.options.getValue("parentIgnore")
for (const reflection of context.project.getReflectionsByKind(
ReflectionKind.All
)) {
if (
isParentIgnoreEnabled &&
reflection instanceof DeclarationReflection
) {
reflection.comment?.blockTags
.filter((tag) => tag.tag === "@parentIgnore")
.forEach((tag) => {
const fieldNames = tag.content
.map((content) => content.text)
.join("")
.split(",")
reflection.children = reflection.children?.filter(
(child) => !fieldNames.includes(child.name)
)
})
}
if (reflection.comment) {
reflection.comment.blockTags = reflection.comment?.blockTags.filter(
(tag) => tag.tag !== "@parentIgnore"
)
}
}
})
}
docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts
+83 -15
View File
@@ -32,10 +32,18 @@ export function load(app: Application) {
defaultValue: false,
})
app.options.addDeclaration({
name: "checkVariables",
help: "Whether to check for and add variables.",
type: ParameterType.Boolean,
defaultValue: false,
})
let activeReflection: Reflection | undefined
const referencedSymbols = new Map<ts.Program, Set<ts.Symbol>>()
const symbolToActiveRefl = new Map<ts.Symbol, Reflection>()
const knownPrograms = new Map<Reflection, ts.Program>()
let checkedVariableSymbols = false
function discoverMissingExports(
context: Context,
@@ -90,6 +98,48 @@ export function load(app: Application) {
}
)
app.converter.on(Converter.EVENT_CREATE_DECLARATION, (context: Context) => {
if (!app.options.getValue("checkVariables") || checkedVariableSymbols) {
return
}
checkedVariableSymbols = true
context.program
.getSourceFiles()
.filter((file) =>
app.entryPoints.some((entryPoint) => file.fileName.includes(entryPoint))
)
.forEach((file) => {
if ("locals" in file) {
const localVariables = file.locals as Map<string, ts.Symbol>
if (!localVariables.size) {
return
}
const internalNs = getOrCreateInternalNs({
context,
scope: context.project,
nameSuffix: `${Math.random() * 100}`,
})
if (!internalNs) {
return
}
const internalContext = context.withScope(internalNs)
for (const [, value] of localVariables) {
if (!value.valueDeclaration) {
continue
}
if (shouldConvertSymbol(value, context.checker)) {
internalContext.converter.convertSymbol(internalContext, value)
}
}
}
})
})
app.converter.on(
Converter.EVENT_RESOLVE_BEGIN,
function onResolveBegin(context: Context) {
@@ -118,21 +168,7 @@ export function load(app: Application) {
// Nasty hack here that will almost certainly break in future TypeDoc versions.
context.setActiveProgram(program)
const internalModuleOption =
context.converter.application.options.getValue("internalModule")
let internalNs: DeclarationReflection | undefined = undefined
if (internalModuleOption) {
internalNs = context
.withScope(mod)
.createDeclarationReflection(
ReflectionKind.Module,
void 0,
void 0,
context.converter.application.options.getValue("internalModule")
)
context.finalizeDeclarationReflection(internalNs)
}
const internalNs = getOrCreateInternalNs({ context, scope: mod })
const internalContext = context.withScope(internalNs || mod)
@@ -199,3 +235,35 @@ function shouldConvertSymbol(symbol: ts.Symbol, checker: ts.TypeChecker) {
return true
}
function getOrCreateInternalNs({
context,
scope,
nameSuffix = "",
}: {
context: Context
scope: Reflection
nameSuffix?: string
}): DeclarationReflection | undefined {
const internalNsName =
context.converter.application.options.getValue("internalModule")
if (!internalNsName) {
return undefined
}
let internalNs = context.project.getChildByName(
`${internalNsName}${nameSuffix}`
) as DeclarationReflection
if (!internalNs) {
internalNs = context
.withScope(scope)
.createDeclarationReflection(
ReflectionKind.Module,
void 0,
void 0,
`${internalNsName}${nameSuffix}`
)
context.finalizeDeclarationReflection(internalNs)
}
return internalNs
}
docs-util/packages/types/lib/index.d.ts
Vendored
+10
View File
@@ -205,5 +205,15 @@ export declare module "typedoc" {
* Namespace names whose child members should have their own documents.
*/
allReflectionsHaveOwnDocumentInNamespace: string[]
/**
* Whether to ignore items with the `@parentIgnore` tag.
* @defaultValue false
*/
parentIgnore: boolean
/**
* Whether to check for and add variables.
* @defaultValue false
*/
checkVariables: boolean
}
}
docs-util/packages/types/tsconfig.json
+1 -1
View File
@@ -3,5 +3,5 @@
"compilerOptions": {
"rootDir": "lib",
},
"include": ["lib/index.d.ts"]
"include": ["lib"]
}