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

chore: refactored docs-util (#5876)

Browse Source
This commit is contained in:
Shahed Nasser
2023-12-14 18:25:40 +02:00
committed by GitHub
parent 2d79eeeecc
commit fde1e23995
21 changed files with 255 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs-util/.eslintrc.js
View File

@@ -92,11 +92,14 @@ module.exports = {
parserOptions: {
project: [
"./tsconfig.json",
"./packages/react-docs-generator/tsconfig.json",
"./packages/scripts/tsconfig.json",
"./packages/typedoc-config/tsconfig.json",
"./packages/typedoc-frontmatter-plugin/tsconfig.json",
"./packages/typedoc-modules-plugin/tsconfig.json",
"./packages/typedoc-markdown-medusa-plugin/tsconfig.json"
"./packages/typedoc-plugin-custom/tsconfig.json",
"./packages/typedoc-markdown-medusa-plugin/tsconfig.json",
"./packages/types/tsconfig.json",
"./packages/utils/tsconfig.json",
"./packages/workflows-diagrams-generator/tsconfig.json"
]
},
rules: {

4
docs-util/packages/typedoc-config/js-client.js
View File

@@ -14,9 +14,5 @@ module.exports = getConfig({
...globalTypedocOptions.exclude,
path.join(pathPrefix, "packages/medusa-js/src/resources/base.ts"),
],
// internalModule: "internal",
ignoreApi: true,
// outputModules: false,
// outputNamespace: false,
// excludeReferences: true,
})

3
docs-util/packages/typedoc-config/package.json
View File

@@ -12,5 +12,8 @@
"version": "0.0.0",
"dependencies": {
"glob": "^10.3.10"
},
"devDependencies": {
"types": "*"
}
}

2
docs-util/packages/typedoc-config/utils/get-config.js
View File

@@ -14,7 +14,7 @@ function getEntryPoints(entryPointPaths) {
/**
*
* @param {Record<string, any>} param0 - The configuration options
* @param {Partial<import('typedoc').TypeDocOptions>} param0 - The configuration options
* @returns {import('typedoc').TypeDocOptions}
*/
function getConfig({

3
docs-util/packages/typedoc-plugin-custom/src/api-ignore.ts
View File

@@ -15,11 +15,12 @@ export function load(app: Application) {
})
app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => {
const isIgnoreApiEnabled = app.options.getValue("ignoreApi")
for (const reflection of context.project.getReflectionsByKind(
ReflectionKind.All
)) {
if (reflection.comment?.hasModifier("@apiIgnore")) {
if (app.options.getValue("ignoreApi")) {
if (isIgnoreApiEnabled) {
context.project.removeReflection(reflection)
} else {
reflection.comment.removeModifier(`@apiIgnore`)

6
docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts
View File

@@ -12,12 +12,6 @@ import {
ParameterType,
} from "typedoc"
declare module "typedoc" {
export interface TypeDocOptionMap {
internalModule: string
}
}
let hasMonkeyPatched = false
export function load(app: Application) {

6
docs-util/packages/typedoc-plugin-custom/src/types/index.d.ts vendored
View File

@@ -1,6 +0,0 @@
export declare module "typedoc" {
declare interface TypeDocOptionMap {
enableInternalResolve: boolean
internalModule: string
}
}

3
docs-util/packages/typedoc-plugin-custom/tsconfig.json
View File

@@ -4,6 +4,5 @@
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src", "src/types"],
"typeRoots": ["./src/types/index.d.ts"]
"include": ["src"]
}

1
docs-util/packages/typedoc-plugin-markdown-medusa/package.json
View File

@@ -23,6 +23,7 @@
"devDependencies": {
"@types/node": "^16.11.10",
"copyfiles": "^2.4.1",
"types": "*",
"typescript": "5.2"
},
"keywords": [

2
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts
View File

@@ -5,7 +5,7 @@ export default function () {
Handlebars.registerHelper(
"hasMoreThanOneSignature",
function (model: DeclarationReflection) {
return (model.signatures?.length || 0) > 1
return (model?.signatures?.length || 0) > 1
}
)
}

2
docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/section-enabled.ts
View File

@@ -1,6 +1,6 @@
import { SectionKey } from "types"
import { MarkdownTheme } from "../../theme"
import * as Handlebars from "handlebars"
import { SectionKey } from "../../types"
export default function (theme: MarkdownTheme) {
Handlebars.registerHelper(

13
docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts
View File

@@ -20,12 +20,13 @@ import {
registerPartials,
} from "./render-utils"
import { formatContents } from "./utils"
import {
import type {
FormattingOptionType,
FormattingOptionsType,
Mapping,
ObjectLiteralDeclarationStyle,
} from "./types"
ParameterStyle,
} from "types"
import { Mapping } from "./types"
export class MarkdownTheme extends Theme {
allReflectionsHaveOwnDocument!: string[]
@@ -44,7 +45,7 @@ export class MarkdownTheme extends Theme {
out!: string
publicPath!: string
preserveAnchorCasing!: boolean
objectLiteralTypeDeclarationStyle: ObjectLiteralDeclarationStyle
objectLiteralTypeDeclarationStyle: ParameterStyle
formattingOptions: FormattingOptionsType
mdxOutput: boolean
outputNamespace: boolean
@@ -84,7 +85,7 @@ export class MarkdownTheme extends Theme {
) as boolean
this.objectLiteralTypeDeclarationStyle = this.getOption(
"objectLiteralTypeDeclarationStyle"
) as ObjectLiteralDeclarationStyle
) as ParameterStyle
this.formattingOptions = this.getOption(
"formatting"
) as FormattingOptionsType

130
docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts
View File

@@ -3,88 +3,12 @@ import {
DeclarationReflection,
PageEvent,
ParameterReflection,
Reflection,
ReflectionKind,
TypeParameterReflection,
} from "typedoc"
export type ParameterStyle = "table" | "list" | "component"
export type ReflectionTitleOptions = {
typeParameters?: boolean
kind?: boolean
}
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"
| "member_declaration_typeDeclaration"
| "member_declaration_example"
| "member_getteSetter_getSignature"
| "member_getteSetter_setSignature"
| "member_signatures"
| "member_getterSetter"
| "member_reference"
| "member_signature_title"
| "member_signature_comment"
| "member_signature_typeParameters"
| "member_signature_parameters"
| "member_signature_example"
| "member_signature_returns"
| "member_signature_declarationSignatures"
| "member_signature_declarationChildren"
| "member_signature_sources"
| "member_sources_implementationOf"
| "member_sources_inheritedFrom"
| "member_sources_overrides"
| "member_sources_definedIn"
| "members_group_categories"
| "members_categories"
| "title_reflectionPath"
| "reflection_comment"
| "reflection_typeParameters"
| "reflection_hierarchy"
| "reflection_implements"
| "reflection_implementedBy"
| "reflection_callable"
| "reflection_indexable"
export type FormattingOptionType = {
sections?: {
[k in SectionKey]: boolean
}
reflectionGroups?: {
[k: string]: boolean
}
reflectionTitle?: {
kind: boolean
typeParameters: boolean
suffix?: string
fullReplacement?: string
}
reflectionDescription?: string
expandMembers?: boolean
showCommentsAsHeader?: boolean
showCommentsAsDetails?: boolean
parameterStyle?: ParameterStyle
frontmatterData?: Record<string, unknown>
parameterComponent?: string
parameterComponentExtraProps?: Record<string, unknown>
mdxImports?: string[]
maxLevel?: number
}
export type FormattingOptionsType = {
[k: string]: FormattingOptionType
}
export type ReflectionParameterType =
| ParameterReflection
| DeclarationReflection
@@ -107,57 +31,3 @@ export type Parameter = {
expandable: boolean
children?: Parameter[]
}
export class NavigationItem {
title: string
url: string
dedicatedUrls?: string[]
parent?: NavigationItem
children?: NavigationItem[]
isLabel?: boolean
isVisible?: boolean
isCurrent?: boolean
isModules?: boolean
isInPath?: boolean
reflection?: Reflection
constructor(
title?: string,
url?: string,
parent?: NavigationItem,
reflection?: Reflection
) {
this.title = title || ""
this.url = url || ""
this.parent = parent
this.reflection = reflection
if (!url) {
this.isLabel = true
}
if (this.parent) {
if (!this.parent.children) {
this.parent.children = []
}
this.parent.children.push(this)
}
}
static create(
reflection: Reflection,
parent?: NavigationItem,
useShortNames?: boolean
) {
let name: string
if (useShortNames || (parent && parent.parent)) {
name = reflection.name
} else {
name = reflection.getFullName()
}
name = name.trim()
return new NavigationItem(name, reflection.url, parent, reflection)
}
}

1
docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts
View File

@@ -217,6 +217,7 @@ export function reflectionTableFormatter({
reflectionType: parameter,
collapse: "object",
wrapBackticks: true,
getRelativeUrlMethod: Handlebars.helpers.relativeURL,
})
)

182
docs-util/packages/types/lib/index.d.ts vendored Normal file
View File

@@ -0,0 +1,182 @@
export type SectionKey =
| "comment"
| "member_declaration"
| "member_declaration_title"
| "member_declaration_comment"
| "member_declaration_typeParameters"
| "member_declaration_indexSignature"
| "member_declaration_signatures"
| "member_declaration_typeDeclaration"
| "member_declaration_example"
| "member_getteSetter_getSignature"
| "member_getteSetter_setSignature"
| "member_signatures"
| "member_getterSetter"
| "member_reference"
| "member_signature_title"
| "member_signature_comment"
| "member_signature_typeParameters"
| "member_signature_parameters"
| "member_signature_example"
| "member_signature_returns"
| "member_signature_declarationSignatures"
| "member_signature_declarationChildren"
| "member_signature_sources"
| "member_sources_implementationOf"
| "member_sources_inheritedFrom"
| "member_sources_overrides"
| "member_sources_definedIn"
| "members_group_categories"
| "members_categories"
| "title_reflectionPath"
| "reflection_comment"
| "reflection_typeParameters"
| "reflection_hierarchy"
| "reflection_implements"
| "reflection_implementedBy"
| "reflection_callable"
| "reflection_indexable"
export type ParameterStyle = "table" | "list" | "component"
export type FormattingOptionsType = {
[k: string]: FormattingOptionType
}
export type FormattingOptionType = {
sections?: {
[k in SectionKey]: boolean
}
reflectionGroups?: {
[k: string]: boolean
}
reflectionTitle?: {
kind: boolean
typeParameters: boolean
suffix?: string
fullReplacement?: string
}
reflectionDescription?: string
expandMembers?: boolean
showCommentsAsHeader?: boolean
showCommentsAsDetails?: boolean
parameterStyle?: ParameterStyle
frontmatterData?: Record<string, unknown>
parameterComponent?: string
parameterComponentExtraProps?: Record<string, unknown>
mdxImports?: string[]
maxLevel?: number
}
export declare module "typedoc" {
declare interface TypeDocOptionMap {
/**
* Enable resolving internal types.
* @defaultValue false
*/
enableInternalResolve: boolean
/**
* The name of the internal module. Requires enabling `enableInternalResolve`.
* @defaultValue "internal"
*/
internalModule: string
/**
* Whether to remove reflections having the `@apiIgnore` tag.
* @defaultValue false
*/
ignoreApi: boolean
/**
* The path to the ESLint configurations to apply.
*/
eslintPathName: string
/**
* The path to resolve plugins used in the ESLint configurations.
*/
pluginsResolvePath: string
/**
* An object of key-value pairs to be added to frontmatter
*/
frontmatterData: Record<string, unknown>
/**
* [Markdown Plugin] Do not render page title.
* @defaultValue false
*/
hidePageTitle: boolean
/**
* [Markdown Plugin] Do not render breadcrumbs in template.
* @defaultValue false
*/
hideBreadcrumbs: boolean
/**
* [Markdown Plugin] Specifies the base path that all links to be served from. If omitted all urls will be relative.
*/
publicPath: string
/**
* [Markdown Plugin] Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids. Should be set for Bitbucket Server docs.
* @defaultValue false
*/
namedAnchors: boolean
/**
* [Markdown Plugin] Specify module names where all reflections are outputted into seperate files.
*/
allReflectionsHaveOwnDocument: string[]
/**
* [Markdown Plugin] Separator used to format filenames.
* @defaultValue "."
*/
filenameSeparator: string
/**
* [Markdown Plugin] The file name of the entry document.
* @defaultValue "README.md"
*/
entryDocument: string
/**
* [Markdown Plugin] Do not render in-page table of contents items.
* @defaultValue false
*/
hideInPageTOC: boolean
/**
* [Markdown Plugin] Customise the index page title.
*/
indexTitle: string
/**
* [Markdown Plugin] Do not add special symbols for class members.
* @defaultValue true
*/
hideMembersSymbol: boolean
/**
* [Markdown Plugin] Preserve anchor casing when generating links.
* @defaultValue false
*/
preserveAnchorCasing: boolean
/**
* [Markdown Plugin] Specify the Type Declaration Render Style
* @defaultValue table
*/
objectLiteralTypeDeclarationStyle: ParameterStyle
/**
* [Markdown Plugin] Formatting options that can be specified either on a specific document or to all documents
*/
formatting: FormattingOptionType
/**
* [Markdown Plugin] Whether outputted files should have an mdx extension.
* @defaultValue false
*/
mdxOutput: boolean
/**
* [Markdown Plugin] The maximum level to expand when retrieving reflection types.
* @defaultValue 3
*/
maxLevel: number
/**
* [Markdown Plugin] Whether to output modules file for namespaces.
* @defaultValue true
*/
outputNamespace: boolean
/**
* [Markdown Plugin] Whether to output module files.
* @defaultValue true
*/
outputModules: boolean
}
}

2
docs-util/packages/types/lib/index.js Normal file
View File

@@ -0,0 +1,2 @@
// noop
module.exports = {}

22
docs-util/packages/types/package.json Normal file
View File

@@ -0,0 +1,22 @@
{
"name": "types",
"private": true,
"license": "MIT",
"publishConfig": {
"access": "public"
},
"scripts": {
"build": "tsc",
"watch": "tsc --watch",
"lint": "eslint --ext .ts src"
},
"peerDependencies": {
"typedoc": "0.25.x"
},
"devDependencies": {
"typescript": "5.2"
},
"version": "0.0.0",
"main": "./lib/index.js",
"types": "./lib/index.d.ts"
}

7
docs-util/packages/types/tsconfig.json Normal file
View File

@@ -0,0 +1,7 @@
{
"extends": "../../tsconfig",
"compilerOptions": {
"rootDir": "lib",
},
"include": ["lib/index.d.ts"]
}

4
docs-util/packages/utils/src/get-type-str.ts
View File

@@ -154,6 +154,7 @@ export function getReflectionType({
collapse,
wrapBackticks = true,
hideLink = false,
...options
}: TypeOptions<ReflectionParameterType>): string {
if ("signatures" in model && model.signatures) {
return collapse === "function" || collapse === "all"
@@ -163,6 +164,7 @@ export function getReflectionType({
wrapBackticks,
hideLink,
escape: !wrapBackticks,
...options,
})
}
return collapse === "object" || collapse === "all"
@@ -172,6 +174,7 @@ export function getReflectionType({
wrapBackticks,
hideLink,
escape: !wrapBackticks,
...options,
})}${wrapBackticks ? "`" : ""}`
}
@@ -347,6 +350,7 @@ export function getReferenceType({
wrapBackticks: false,
hideLink,
escape: false,
getRelativeUrlMethod,
...options,
})
)

3
docs-util/tsconfig.json
View File

@@ -10,7 +10,8 @@
"sourceMap": true,
"skipLibCheck": true,
"rootDir": ".",
"allowJs": true
"allowJs": true,
"typeRoots": ["node_modules/@types", "./packages/types"]
},
"include": ["**/*.ts", "**/*.js"],
"exclude": ["**/node_modules/**", "dist"]

12
docs-util/yarn.lock
View File

@@ -4417,6 +4417,7 @@ __metadata:
resolution: "typedoc-config@workspace:packages/typedoc-config"
dependencies:
glob: ^10.3.10
types: "*"
peerDependencies:
typedoc: 0.25.x
languageName: unknown
@@ -4463,6 +4464,7 @@ __metadata:
"@types/node": ^16.11.10
copyfiles: ^2.4.1
handlebars: ^4.7.8
types: "*"
typescript: 5.2
utils: "*"
peerDependencies:
@@ -4544,6 +4546,16 @@ __metadata:
languageName: node
linkType: hard
"types@*, types@workspace:packages/types":
version: 0.0.0-use.local
resolution: "types@workspace:packages/types"
dependencies:
typescript: 5.2
peerDependencies:
typedoc: 0.25.x
languageName: unknown
linkType: soft
"typescript@npm:5.2":
version: 5.2.2
resolution: "typescript@npm:5.2.2"