diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts index 3f469f8f..cf2fc665 100644 --- a/devtools/packages/prebuild-options/tasks/generate-docs.ts +++ b/devtools/packages/prebuild-options/tasks/generate-docs.ts @@ -149,7 +149,6 @@ ${presetsJson} } if (!option.omitExample) { - //out.push('**Example**'); if ( !option.example && option.type === ParameterType.Mixed && diff --git a/devtools/packages/testing/package.json b/devtools/packages/testing/package.json index 13890797..eaf2ea7c 100644 --- a/devtools/packages/testing/package.json +++ b/devtools/packages/testing/package.json @@ -5,8 +5,5 @@ "main": "index.ts", "files": [ "/" - ], - "bin": { - "lint-mdx": "lint-mdx.mjs" - } + ] } diff --git a/devtools/scripts/generate-schema/generate-schema.ts b/devtools/scripts/generate-schema/generate-schema.ts new file mode 100644 index 00000000..ff357382 --- /dev/null +++ b/devtools/scripts/generate-schema/generate-schema.ts @@ -0,0 +1,24 @@ +import * as fs from 'fs'; +import * as options from '../../../packages/typedoc-plugin-markdown/src/options/declarations'; + +main(); + +async function main() { + const { getSchema } = await import('./get-scheme.cjs'); + const schema = await getSchema(); + + for (const key in schema.properties) { + schema.properties[key].default = + options[key].defaultValue || options[key].defaults; + if (schema.properties[key].required) { + delete schema.properties[key].required; + } + } + + if (schema.required) { + delete schema.required; + } + + const schemaString = JSON.stringify(schema, null, 2); + fs.writeFileSync('./docs/public/schema.json', schemaString); +} diff --git a/devtools/scripts/generate-schema/get-scheme.cjs b/devtools/scripts/generate-schema/get-scheme.cjs new file mode 100755 index 00000000..352c9645 --- /dev/null +++ b/devtools/scripts/generate-schema/get-scheme.cjs @@ -0,0 +1,14 @@ +module.exports = { + getSchema: async () => { + /** @type {import('ts-json-schema-generator/dist/src/Config').Config} */ + const config = { + path: 'packages/typedoc-plugin-markdown/src/options/option-types.ts', + tsconfig: 'tsconfig.schema.json', + type: 'PluginOptions', + topRef: false, + }; + const { createGenerator } = await import('ts-json-schema-generator'); + const schema = createGenerator(config).createSchema(config.type); + return schema; + }, +}; diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx index 85021071..564e44c8 100644 --- a/docs/pages/docs/options.mdx +++ b/docs/pages/docs/options.mdx @@ -430,7 +430,7 @@ This option either renders properties for classes and interfaces as a list or in ### enumMembersFormat -Specify the render style of enumuration members. +Specify the render style of enumeration members. > Accepts either `"list"` or `"table"`. Defaults to `"list"`. @@ -452,7 +452,7 @@ This option either renders members of enums as a list or in tabular format. > Accepts either `"list"` or `"table"`. Defaults to `"list"`. -This option either renders type declrations as a list or in tabular format. +This option either renders type declarations as a list or in tabular format. ```json filename="typedoc.json" { @@ -614,7 +614,7 @@ By default all comments written inside JsDoc comments will be passed to the outp This option will escape angle brackets `<` `>` and curly braces `{` `}` written inside JsDoc comments. -This option would typically be used when source code comes from an external library exposing the following poential issues: +This option would typically be used when source code comes from an external library exposing the following potential issues: - Comments contain raw tags that should be interpreted as code examples. - Comments contain invalid syntax that (in the case of MDX) will cause breaking parsing errors. @@ -634,7 +634,7 @@ This option would typically be used when source code comes from an external libr > Accepts a string value. Defaults to `"undefined"`. -This option should be used when parsers requiren a custom anchor prefix. +This option should be used when parsers require a custom anchor prefix. ```json filename="typedoc.json" { diff --git a/docs/public/schema.json b/docs/public/schema.json new file mode 100644 index 00000000..d0fd8e3d --- /dev/null +++ b/docs/public/schema.json @@ -0,0 +1,454 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "anchorPrefix": { + "type": "string", + "description": "Custom anchor prefix" + }, + "entryFileName": { + "type": "string", + "description": "The file name of the entry page.", + "default": "README" + }, + "entryModule": { + "type": "string", + "description": "The name of a module that should act as the root page for the documentation." + }, + "enumMembersFormat": { + "type": "string", + "enum": [ + "list", + "table" + ], + "description": "Specify the render style of enumeration members.", + "default": "list" + }, + "excludeGroups": { + "type": "boolean", + "description": "Excludes grouping by kind so all members are rendered and sorted at the same level." + }, + "excludeScopesInPaths": { + "type": "boolean", + "description": "Exclude writing @ scope directories in paths." + }, + "expandObjects": { + "type": "boolean", + "description": "Expand objects inside declarations." + }, + "expandParameters": { + "type": "boolean", + "description": "Expand parameters in signature parentheses to display type information." + }, + "fileExtension": { + "type": "string", + "description": "Specify the file extension for generated output files.", + "default": ".md" + }, + "flattenOutputFiles": { + "type": "boolean", + "description": "Flatten output files to a single directory." + }, + "hideBreadcrumbs": { + "type": "boolean", + "description": "Do not print breadcrumbs." + }, + "hidePageHeader": { + "type": "boolean", + "description": "Do not print page header." + }, + "hidePageTitle": { + "type": "boolean", + "description": "Do not print page title." + }, + "indexFormat": { + "type": "string", + "enum": [ + "list", + "table" + ], + "description": "Specify the render format for index items.", + "default": "list" + }, + "membersWithOwnFile": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "Enum", + "Variable", + "Function", + "Class", + "Interface", + "TypeAlias" + ] + }, + "description": "Determines which members are exported to their own file when `outputFileStrategy` equals `members`.", + "default": [ + "Enum", + "Variable", + "Function", + "Class", + "Interface", + "TypeAlias" + ] + }, + "mergeReadme": { + "type": "boolean", + "description": "Merges the resolved readme into the project index page." + }, + "navigationModel": { + "type": "object", + "properties": { + "excludeGroups": { + "type": "boolean" + }, + "excludeCategories": { + "type": "boolean" + }, + "excludeFolders": { + "type": "boolean" + } + }, + "additionalProperties": false, + "description": "Configures how the navigation model will be generated.", + "default": { + "excludeGroups": false, + "excludeCategories": false, + "excludeFolders": false + } + }, + "outputFileStrategy": { + "type": "string", + "enum": [ + "members", + "modules" + ], + "description": "Determines how output files are generated.", + "default": "members" + }, + "parametersFormat": { + "type": "string", + "enum": [ + "list", + "table" + ], + "description": "Specify the render style of parameter and type parameter groups.", + "default": "list" + }, + "preserveAnchorCasing": { + "type": "boolean", + "description": "Preserve anchor casing when generating link to symbols." + }, + "propertiesFormat": { + "type": "string", + "enum": [ + "list", + "table" + ], + "description": "Specify the render style of property groups for interfaces and classes.", + "default": "list" + }, + "publicPath": { + "type": "string", + "description": "Specify the base path for all urls." + }, + "sanitizeComments": { + "type": "boolean", + "description": "Sanitize HTML and JSX inside JsDoc comments." + }, + "textContentMappings": { + "type": "object", + "properties": { + "header.title": { + "type": "string" + }, + "header.readme": { + "type": "string" + }, + "header.docs": { + "type": "string" + }, + "breadcrumbs.home": { + "type": "string" + }, + "title.indexPage": { + "type": "string" + }, + "title.modulePage": { + "type": "string" + }, + "title.memberPage": { + "type": "string" + }, + "label.apiIndex": { + "type": "string" + }, + "label.defaultValue": { + "type": "string" + }, + "label.description": { + "type": "string" + }, + "label.extendedBy": { + "type": "string" + }, + "label.extends": { + "type": "string" + }, + "label.flags": { + "type": "string" + }, + "label.globals": { + "type": "string" + }, + "label.implements": { + "type": "string" + }, + "label.implementationOf": { + "type": "string" + }, + "label.inheritedFrom": { + "type": "string" + }, + "label.index": { + "type": "string" + }, + "label.indexable": { + "type": "string" + }, + "label.indexSignature": { + "type": "string" + }, + "label.member": { + "type": "string" + }, + "label.modifier": { + "type": "string" + }, + "label.name": { + "type": "string" + }, + "label.overrides": { + "type": "string" + }, + "label.packages": { + "type": "string" + }, + "label.reExports": { + "type": "string" + }, + "label.renamesAndReExports": { + "type": "string" + }, + "label.returns": { + "type": "string" + }, + "label.source": { + "type": "string" + }, + "label.type": { + "type": "string" + }, + "label.typeDeclaration": { + "type": "string" + }, + "label.value": { + "type": "string" + }, + "kind.accessor.singular": { + "type": "string" + }, + "kind.accessor.plural": { + "type": "string" + }, + "kind.class.singular": { + "type": "string" + }, + "kind.class.plural": { + "type": "string" + }, + "kind.constructor.singular": { + "type": "string" + }, + "kind.constructor.plural": { + "type": "string" + }, + "kind.enum.singular": { + "type": "string" + }, + "kind.enum.plural": { + "type": "string" + }, + "kind.enumMember.singular": { + "type": "string" + }, + "kind.enumMember.plural": { + "type": "string" + }, + "kind.event.singular": { + "type": "string" + }, + "kind.event.plural": { + "type": "string" + }, + "kind.function.singular": { + "type": "string" + }, + "kind.function.plural": { + "type": "string" + }, + "kind.interface.singular": { + "type": "string" + }, + "kind.interface.plural": { + "type": "string" + }, + "kind.method.singular": { + "type": "string" + }, + "kind.method.plural": { + "type": "string" + }, + "kind.module.singular": { + "type": "string" + }, + "kind.module.plural": { + "type": "string" + }, + "kind.namespace.singular": { + "type": "string" + }, + "kind.namespace.plural": { + "type": "string" + }, + "kind.variable.singular": { + "type": "string" + }, + "kind.variable.plural": { + "type": "string" + }, + "kind.parameter.singular": { + "type": "string" + }, + "kind.parameter.plural": { + "type": "string" + }, + "kind.property.singular": { + "type": "string" + }, + "kind.property.plural": { + "type": "string" + }, + "kind.reference.singular": { + "type": "string" + }, + "kind.reference.plural": { + "type": "string" + }, + "kind.typeAlias.singular": { + "type": "string" + }, + "kind.typeAlias.plural": { + "type": "string" + }, + "kind.typeParameter.singular": { + "type": "string" + }, + "kind.typeParameter.plural": { + "type": "string" + } + }, + "additionalProperties": false, + "description": "Provides a mechanism to change the content of text used in documentation.", + "default": { + "header.title": "{projectName} {version}", + "header.readme": "Readme", + "header.docs": "Docs", + "breadcrumbs.home": "{projectName} {version}", + "title.indexPage": "{projectName} {version}", + "title.modulePage": "{name}", + "title.memberPage": "{kind}: {name}", + "label.apiIndex": "API Index", + "label.defaultValue": "Default value", + "label.description": "Description", + "label.extendedBy": "Extended by", + "label.extends": "Extends", + "label.flags": "Flags", + "label.globals": "Globals", + "label.implements": "Implements", + "label.implementationOf": "Implementation of", + "label.inheritedFrom": "Inherited from", + "label.index": "Index", + "label.indexable": "Indexable", + "label.indexSignature": "Index signature", + "label.member": "Member", + "label.modifier": "Modifier", + "label.name": "Name", + "label.overrides": "Overrides", + "label.packages": "Packages", + "label.reExports": "Re-exports", + "label.renamesAndReExports": "Renames and re-exports", + "label.returns": "Returns", + "label.source": "Source", + "label.type": "Type", + "label.typeDeclaration": "Type declaration", + "label.value": "Value", + "kind.accessor.singular": "Accessor", + "kind.accessor.plural": "Accessors", + "kind.class.singular": "Class", + "kind.class.plural": "Classes", + "kind.constructor.singular": "Constructor", + "kind.constructor.plural": "Constructors", + "kind.enum.singular": "Enumeration", + "kind.enum.plural": "Enumerations", + "kind.enumMember.singular": "Enumeration Member", + "kind.enumMember.plural": "Enumeration Members", + "kind.event.singular": "Event", + "kind.event.plural": "Events", + "kind.function.singular": "Function", + "kind.function.plural": "Functions", + "kind.interface.singular": "Interface", + "kind.interface.plural": "Interfaces", + "kind.method.singular": "Method", + "kind.method.plural": "Methods", + "kind.module.singular": "Module", + "kind.module.plural": "Modules", + "kind.namespace.singular": "Namespace", + "kind.namespace.plural": "Namespaces", + "kind.variable.singular": "Variable", + "kind.variable.plural": "Variables", + "kind.parameter.singular": "Parameter", + "kind.parameter.plural": "Parameters", + "kind.property.singular": "Property", + "kind.property.plural": "Properties", + "kind.reference.singular": "Reference", + "kind.reference.plural": "References", + "kind.typeAlias.singular": "Type alias", + "kind.typeAlias.plural": "Type Aliases", + "kind.typeParameter.singular": "Type parameter", + "kind.typeParameter.plural": "Type parameters" + } + }, + "typeDeclarationFormat": { + "type": "string", + "enum": [ + "list", + "table" + ], + "description": "Specify the render style for type declaration members.", + "default": "list" + }, + "useCodeBlocks": { + "type": "boolean", + "description": "Wraps signatures and declarations in code blocks." + }, + "useHTMLAnchors": { + "type": "boolean", + "description": "Add HTML named anchors to headings and table rows." + } + }, + "additionalProperties": false, + "description": "Describes the options declared by the plugin.", + "definitions": {} +} \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 8c629142..6d4eddc1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -37,6 +37,7 @@ "remark-toc": "^9.0.0", "to-vfile": "^8.0.0", "ts-jest": "^29.1.2", + "ts-json-schema-generator": "^2.1.1", "ts-morph": "^22.0.0", "ts-node": "^10.9.2", "tsc-alias": "^1.8.8", @@ -65,10 +66,7 @@ }, "devtools/packages/testing": { "name": "@devtools/testing", - "version": "0.0.0", - "bin": { - "lint-mdx": "lint-mdx.mjs" - } + "version": "0.0.0" }, "node_modules/@aashutoshrathi/word-wrap": { "version": "1.2.6", @@ -18490,6 +18488,15 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/safe-stable-stringify": { + "version": "2.4.3", + "resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.4.3.tgz", + "integrity": "sha512-e2bDA2WJT0wxseVd4lsDP4+3ONX6HpMXQa1ZhFQ7SU+GjvORCmShbCMltrtIDfkYhVHrOcPtj+KhmDBdPdZD1g==", + "dev": true, + "engines": { + "node": ">=10" + } + }, "node_modules/safer-buffer": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", @@ -20243,6 +20250,36 @@ "node": ">=12" } }, + "node_modules/ts-json-schema-generator": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/ts-json-schema-generator/-/ts-json-schema-generator-2.1.1.tgz", + "integrity": "sha512-ha5/w3A2APOOn9ET2CfunEXdVOnKmjISTGcxhCkDszmrsRWFfG5F+re5U5onLXo665sZ4BuE2g5jZAjC+CUcgA==", + "dev": true, + "dependencies": { + "@types/json-schema": "^7.0.15", + "commander": "^12.0.0", + "glob": "^10.3.12", + "json5": "^2.2.3", + "normalize-path": "^3.0.0", + "safe-stable-stringify": "^2.4.3", + "typescript": "^5.4.5" + }, + "bin": { + "ts-json-schema-generator": "bin/ts-json-schema-generator.js" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/ts-json-schema-generator/node_modules/commander": { + "version": "12.0.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-12.0.0.tgz", + "integrity": "sha512-MwVNWlYjDTtOjX5PiD7o5pK0UrFU/OYgcJfjjK4RaHZETNtjJqrZa9Y9ds88+A+f+d5lv+561eZ+yCKoS3gbAA==", + "dev": true, + "engines": { + "node": ">=18" + } + }, "node_modules/ts-morph": { "version": "22.0.0", "resolved": "https://registry.npmjs.org/ts-morph/-/ts-morph-22.0.0.tgz", @@ -22161,7 +22198,7 @@ } }, "packages/docusaurus-plugin-typedoc": { - "version": "1.0.0-next.29", + "version": "1.0.0-next.30", "license": "MIT", "devDependencies": { "@docusaurus/core": "^3.2.1", @@ -22196,7 +22233,7 @@ } }, "packages/typedoc-plugin-markdown": { - "version": "4.0.0-next.56", + "version": "4.0.0-next.58", "license": "MIT", "peerDependencies": { "typedoc": "0.25.x" diff --git a/package.json b/package.json index ddfa0853..031363b8 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "build-all": "npm run build --workspaces --if-present", "test-all": "npm run test --workspaces --if-present", "prerelease": "npm run build-all", - "release": "npx changeset publish" + "release": "npx changeset publish", + "schema": "ts-node ./devtools/scripts/generate-schema/generate-schema.ts" }, "devDependencies": { "@changesets/cli": "^2.27.1", @@ -40,6 +41,7 @@ "remark-toc": "^9.0.0", "to-vfile": "^8.0.0", "ts-jest": "^29.1.2", + "ts-json-schema-generator": "^2.1.1", "ts-morph": "^22.0.0", "ts-node": "^10.9.2", "tsc-alias": "^1.8.8", diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts index 1aa84433..39b7bfc8 100644 --- a/packages/typedoc-plugin-markdown/src/options/declarations.ts +++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts @@ -352,14 +352,14 @@ export const propertiesFormat: Partial = { * @category UX */ export const enumMembersFormat: Partial = { - help: 'Specify the render style of enumuration members.', + help: 'Specify the render style of enumeration members.', type: ParameterType.Map, map: FormatStyle, defaultValue: FormatStyle.List, }; /** - * This option either renders type declrations as a list or in tabular format. + * This option either renders type declarations as a list or in tabular format. * * @category UX */ @@ -461,7 +461,7 @@ export const publicPath: Partial = { * * This option will escape angle brackets `<` `>` and curly braces `{` `}` written inside JsDoc comments. * - * This option would typically be used when source code comes from an external library exposing the following poential issues: + * This option would typically be used when source code comes from an external library exposing the following potential issues: * * - Comments contain raw tags that should be interpreted as code examples. * - Comments contain invalid syntax that (in the case of MDX) will cause breaking parsing errors. @@ -476,7 +476,7 @@ export const sanitizeComments: Partial = { }; /** - * This option should be used when parsers requiren a custom anchor prefix. + * This option should be used when parsers require a custom anchor prefix. * * @example "markdown-header" * diff --git a/packages/typedoc-plugin-markdown/src/options/option-types.ts b/packages/typedoc-plugin-markdown/src/options/option-types.ts index 9b1e610b..e9624ccb 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-types.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-types.ts @@ -67,7 +67,7 @@ export interface PluginOptions { entryModule: string; /** - * Specify the render style of enumuration members. + * Specify the render style of enumeration members. */ enumMembersFormat: 'list' | 'table'; diff --git a/tsconfig.schema.json b/tsconfig.schema.json new file mode 100644 index 00000000..c0ac5cd1 --- /dev/null +++ b/tsconfig.schema.json @@ -0,0 +1,9 @@ +{ + "compilerOptions": { + "esModuleInterop": true, + "lib": ["es2021", "dom"], + "module": "ESNext", + "moduleResolution": "node", + "target": "es2021" + } +}