feat(core): [email protected] release

typedoc2md · May 18, 2024 · 416f958 · 416f958
1 parent 196c2a9
commit 416f958
Show file tree

Hide file tree

Showing 81 changed files with 1,161 additions and 1,153 deletions.
diff --git a/devtools/packages/fixtures/DOCUMENT_1.md b/devtools/packages/fixtures/DOCUMENT_1.md
@@ -0,0 +1,5 @@
+---
+title: 'Document Hello'
+---
+
+# Document 1
diff --git a/devtools/packages/fixtures/DOCUMENT_2.md b/devtools/packages/fixtures/DOCUMENT_2.md
@@ -0,0 +1 @@
+# Document 2
diff --git a/devtools/packages/fixtures/cli.ts b/devtools/packages/fixtures/cli.ts
@@ -41,7 +41,7 @@ async function main() {
     const outputFileStrategies: ('members' | 'modules')[] =
       config.outputFileStrategies || ['members', 'modules'];
 
-    //writeHtml(key, config.entryPoints);
+    writeHtml(key, config.entryPoints);
     outputFileStrategies.forEach((outputFileStrategy) => {
       config.options.forEach((optionGroup, index: number) => {
         const options = {
@@ -117,6 +117,14 @@ export function writeHtml(key: string, entryPoints: string[]) {
         'Warn',
         '-out',
         fullPath,
+        '-readme',
+        'none',
+        '-projectDocuments',
+        path.join(__dirname, 'DOCUMENT_1.md'),
+        '-projectDocuments',
+        path.join(__dirname, 'DOCUMENT_2.md'),
+        '-projectDocuments',
+        path.join(__dirname, 'subdocs/DOCUMENT_3.md'),
       ],
       ...toEntryPoints(entryPoints),
     ],

diff --git a/devtools/packages/fixtures/subdocs/DOCUMENT_3.md b/devtools/packages/fixtures/subdocs/DOCUMENT_3.md
@@ -0,0 +1 @@
+# Document 3
diff --git a/devtools/packages/helpers/constants.ts b/devtools/packages/helpers/constants.ts
@@ -1,10 +1,12 @@
 import { DocsConfig } from './models';
 
+export const SRC_PATH = `${process.cwd()}/src`;
 export const PRESETS_PATH = `${process.cwd()}/src/options/presets.ts`;
 
 export const DOCS_CONFIG: Record<string, DocsConfig> = {
   ['typedoc-plugin-markdown']: {
     declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
+    translatablePath: `${process.cwd()}/src/app/translatable.ts`,
     optionsPath: '/docs',
     docsPath: '/docs',
     declarations: true,

diff --git a/devtools/packages/helpers/models.ts b/devtools/packages/helpers/models.ts
@@ -1,5 +1,6 @@
 export interface DocsConfig {
   declarationsPath?: string;
+  translatablePath?: string;
   presetsPath?: string;
   optionsPath: string;
   docsPath: string;

diff --git a/devtools/packages/prebuild-options/tasks/generate-models.ts b/devtools/packages/prebuild-options/tasks/generate-models.ts
@@ -1,4 +1,4 @@
-import { DocsConfig } from '@devtools/helpers';
+import { DocsConfig, SRC_PATH } from '@devtools/helpers';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as prettier from 'prettier';
@@ -11,37 +11,76 @@ import { DeclarationOption, ParameterType } from 'typedoc';
 export async function generateOptionsModels(docsConfig: DocsConfig) {
   const optionsConfig = await import(docsConfig.declarationsPath as string);
 
-  const mixedTypes = (Object.entries(optionsConfig) as any).filter(
-    ([name, option]) =>
-      option.type === ParameterType.Mixed && option.defaultValue,
+  const sortedOptionsConfig = Object.fromEntries(
+    Object.entries(optionsConfig).sort((a, b) => a[0].localeCompare(b[0])),
   );
 
-  const containsManuallyValidatedOptions = Object.values(optionsConfig).some(
+  await writeTypeDocDeclarations(docsConfig, sortedOptionsConfig);
+  await writeOptionsTypes(docsConfig, sortedOptionsConfig);
+}
+
+async function writeTypeDocDeclarations(
+  docsConfig: DocsConfig,
+  sortedOptionsConfig: any,
+) {
+  const typedocDeclarationsFile = path.join(SRC_PATH, 'defs', 'typedoc.d.ts');
+
+  const containsManuallyValidatedOptions = Object.values(
+    sortedOptionsConfig,
+  ).some(
     (option) =>
       (option as any).type === ParameterType.Mixed &&
       (option as any).defaultValue,
   );
 
-  const sortedOptionsConfig = Object.fromEntries(
-    Object.entries(optionsConfig).sort((a, b) => a[0].localeCompare(b[0])),
+  const out: string[] = [];
+
+  out.push(
+    `// THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
+
+${
+  containsManuallyValidatedOptions &&
+  `import { ManuallyValidatedOption } from 'typedoc'`
+};
+`,
+  );
+  out.push(`declare module 'typedoc' {`);
+  out.push(`export interface TypeDocOptionMap {
+    ${(Object.entries(sortedOptionsConfig) as any)
+      .map(([name, option]) => `${name}: ${getType(name, option)};`)
+      .join('\n')}
+  }`);
+
+  if (docsConfig.translatablePath) {
+    const { translatable } = await import(docsConfig.translatablePath);
+    out.push(`
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  export namespace Internationalization {
+    export interface TranslatableStrings ${getTranslations(translatable)}
+  }`);
+  }
+  out.push(`}`);
+  const formatted = await prettier.format(out.join('\n'), {
+    parser: 'typescript',
+    singleQuote: true,
+    trailingComma: 'all',
+  });
+
+  fs.writeFileSync(typedocDeclarationsFile, formatted);
+}
+
+async function writeOptionsTypes(
+  docsConfig: DocsConfig,
+  sortedOptionsConfig: any,
+) {
+  const mixedTypes = (Object.entries(sortedOptionsConfig) as any).filter(
+    ([name, option]) =>
+      option.type === ParameterType.Mixed && option.defaultValue,
   );
 
   const optionsOutput = `
   // THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
 
-  ${
-    containsManuallyValidatedOptions &&
-    `import { ManuallyValidatedOption } from 'typedoc'`
-  };
-
-  declare module 'typedoc' {
-    export interface TypeDocOptionMap {
-      ${(Object.entries(sortedOptionsConfig) as any)
-        .map(([name, option]) => `${name}: ${getType(name, option)};`)
-        .join('\n')}
-    }
-  }
-
   /**
    * Describes the options declared by the plugin.
    *
@@ -94,6 +133,15 @@ ${name}: ${getType(name, option, true)};`,
   fs.writeFileSync(optionsModelFile, formatted);
 }
 
+function getTranslations(inputObject: { [key: string]: string }) {
+  const output: { [key: string]: string[] } = {};
+  for (const [key, value] of Object.entries(inputObject)) {
+    const matches = value.match(/{\d+}/g) || [];
+    output[key] = matches.map(() => 'string');
+  }
+  return JSON.stringify(output).replace(/"/g, '');
+}
+
 function getComments(name: string) {
   if (name === 'textContentMappings') {
     return 'Describes the keys available to replace static text.';
@@ -148,11 +196,11 @@ function getType(
     const usePartial = name === 'textContentMappings';
     return isInterface
       ? usePartial
-        ? `Partial<${capitalize(name)}>`
+        ? `Partial<any>`
         : capitalize(name)
       : usePartial
-        ? `ManuallyValidatedOption<Partial<${capitalize(name)}>>`
-        : `ManuallyValidatedOption<${capitalize(name)}>`;
+        ? `ManuallyValidatedOption<Partial<any>>`
+        : `ManuallyValidatedOption<any>`;
   }
 
   if (option.type === ParameterType.Map && option.map) {

diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx
@@ -540,74 +540,7 @@ Only keys that require translation need to be added to the object.
 
 ```json filename="typedoc.json"
 {
-  "textContentMappings": {
-    "header.title": "{projectName} {version}",
-    "header.docs": "Docs",
-    "breadcrumbs.home": "{projectName} {version}",
-    "footer.text": "",
-    "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"
-  }
+  "textContentMappings": {}
 }
 ```