feat(core): [email protected] documents implementation

typedoc2md · May 25, 2024 · 3bfe42b · 3bfe42b
1 parent b5a03c8
commit 3bfe42b
Show file tree

Hide file tree

Showing 129 changed files with 4,721 additions and 1,548 deletions.
diff --git a/devtools/examples/docusaurus/docusaurus.config.js b/devtools/examples/docusaurus/docusaurus.config.js
@@ -58,17 +58,24 @@ const config = {
           __dirname,
           '../../../packages/typedoc-plugin-markdown/test/fixtures/tsconfig.json',
         ),
-        entryPoints:
-          '../../../packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts',
+        entryPoints: [
+          '../../../packages/typedoc-plugin-markdown/test/fixtures/src/documents/module-1.ts',
+          '../../../packages/typedoc-plugin-markdown/test/fixtures/src/documents/module-2.ts',
+        ],
         expandObjects: true,
         readme: 'none',
         sidebar: { pretty: true },
         outputFileStrategy: 'members',
         propertiesFormat: 'htmlTable',
         cleanOutputDir: true,
+        projectDocuments: [
+          '../../../packages/typedoc-plugin-markdown/test/fixtures/PROJECT_DOC_1.md',
+          '../../../packages/typedoc-plugin-markdown/test/fixtures/docs/project/PROJECT_DOC_2.md',
+          '../../../packages/typedoc-plugin-markdown/test/fixtures/docs/project/PROJECT_DOC_3.md',
+        ],
       },
     ],
-    [
+    /*[
       docusaurusPlugin,
       {
         id: 'api-2',
@@ -100,7 +107,7 @@ const config = {
         },
       },
     ],
-    /*[
+   [
       docusaurusPlugin,
       {
         id: 'api-3',

diff --git a/devtools/examples/docusaurus/sidebars.js b/devtools/examples/docusaurus/sidebars.js
@@ -24,7 +24,7 @@ const sidebars = {
       },
       items: require('./docs/api/typedoc-sidebar.cjs'),
     },
-    {
+    /*{
       type: 'category',
       label: 'DOCS 2',
       link: {
@@ -33,7 +33,7 @@ const sidebars = {
       },
       items: require('./docs/api-2/typedoc-sidebar.cjs'),
     },
-    /*{
+    {
       type: 'category',
       label: 'DOCS 3',
       link: {

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 = {
@@ -99,6 +99,10 @@ function writeMarkdown(
 }
 
 export function writeHtml(key: string, entryPoints: string[]) {
+  const fixturesRoot = path.join(
+    __dirname,
+    '../../../packages/typedoc-plugin-markdown/test/fixtures',
+  );
   const fullPath = path.join(
     process.cwd(),
     'test',
@@ -117,6 +121,14 @@ export function writeHtml(key: string, entryPoints: string[]) {
         'Warn',
         '-out',
         fullPath,
+        '-readme',
+        'none',
+        '-projectDocuments',
+        path.join(fixturesRoot, 'PROJECT_DOC_1.md'),
+        '-projectDocuments',
+        path.join(fixturesRoot, 'docs/project/PROJECT_DOC_2.md'),
+        '-projectDocuments',
+        path.join(fixturesRoot, 'docs/project/PROJECT_DOC_3.md'),
       ],
       ...toEntryPoints(entryPoints),
     ],

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,36 +11,75 @@ 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 containsManuallyValidatedOptions = Object.values(optionsConfig).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 optionsOutput = `
-  // THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
+  await writeTypeDocDeclarations(docsConfig, sortedOptionsConfig);
+  await writeOptionsTypes(docsConfig, sortedOptionsConfig);
+}
 
-  ${
-    containsManuallyValidatedOptions &&
-    `import { ManuallyValidatedOption } from 'typedoc'`
-  };
+async function writeTypeDocDeclarations(
+  docsConfig: DocsConfig,
+  sortedOptionsConfig: any,
+) {
+  const typedocDeclarationsFile = path.join(SRC_PATH, 'defs', 'typedoc.d.ts');
+
+  const manuallyValidatedOptions = Object.entries(sortedOptionsConfig)
+    .filter(
+      ([name, option]) =>
+        (option as any).type === ParameterType.Mixed &&
+        (option as any).defaultValue,
+    )
+    .map(([name, option]) => capitalize(name));
+
+  const out: string[] = [];
+
+  out.push(`// THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
+import { ManuallyValidatedOption } from 'typedoc'`);
 
-  declare module 'typedoc' {
-    export interface TypeDocOptionMap {
-      ${(Object.entries(sortedOptionsConfig) as any)
-        .map(([name, option]) => `${name}: ${getType(name, option)};`)
-        .join('\n')}
-    }
+  if (manuallyValidatedOptions.length) {
+    manuallyValidatedOptions.forEach((option: any) => {
+      out.push(`import { ${option} } from '../options/option-types';`);
+    });
+  }
+
+  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.
 
   /**
    * 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.';

diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx
@@ -294,6 +294,22 @@ Ignored if `flattenOutputFiles` is set to `true`.
 
 ---
 
+### inlineDocuments
+
+<Callout emoji="💡">Inline documents in pages.</Callout>
+
+> Accepts a boolean value. Defaults to `false`.
+
+By default a documents index and separate documents pages are generated when using the `@document` tag.
+
+```json filename="typedoc.json"
+{
+  "inlineDocuments": false
+}
+```
+
+---
+
 ### excludeGroups
 
 <Callout emoji="💡">
@@ -540,74 +556,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": {}
 }
 ```