fix(core): further typedoc beta fixes

.gitignore

@@ -9,7 +9,7 @@ samples
 out
 typedoc-examples
 html
-/devdocs
+devdocs
 /devdocs-html
 
 # dependencies

CONTRIBUTING.md

@@ -1,3 +1,15 @@
 # Contributing Guide
 
-Coming soon.
+Thank you for showing interest in contributing to this project. This guide provides some basic guidelines for doing so.
+
+## Overview
+
+This project attempts to align with TypeDoc core as much as possible. Before you start, you might find it helpful to read the [TypeDoc development guide]() to understand the architecture of TypeDoc itself.
+
+## Developers Guide
+
+Please visit the [developers guide](./devdocs/README.md) (created by this plugin) for to start developing.
+
+## Credits
+
+Thank you to all the people who have already contributed to typedoc-plugin-markdown.

devtools/packages/fixtures/typedoc.cjs

@@ -15,4 +15,9 @@ module.exports = {
   navigation: {
     includeGroups: true,
   },
+  locales: {
+    en: {
+      theme_defined_in: 'Source',
+    },
+  },
 };

devtools/packages/helpers/constants.ts

@@ -6,7 +6,7 @@ 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`,
+    translatablePath: `${process.cwd()}/src/internationalization/locales/en.ts`,
     optionsPath: '/docs',
     docsPath: '/docs',
     declarations: true,

devtools/packages/prebuild-options/tasks/generate-docs.ts

@@ -160,7 +160,8 @@ ${presetsJson}
         if (
           option.type !== ParameterType.Flags &&
           option.type !== ParameterType.Array &&
-          option.type !== ParameterType.Mixed
+          option.type !== ParameterType.Mixed &&
+          option.type !== ParameterType.Object
         ) {
           meta.push(`Defaults to \`${getDefaultValue(option)}\`.`);
         }
@@ -306,6 +307,9 @@ function getDefaultValue(option) {
   if (option.type === ParameterType.Mixed) {
     return JSON.stringify(option.defaultValue);
   }
+  if (option.type === ParameterType.Object) {
+    return JSON.stringify(option.defaultValue);
+  }
   return `"${option.defaultValue}"`;
 }
 

devtools/packages/prebuild-options/tasks/generate-models.ts

@@ -4,10 +4,6 @@ import * as path from 'path';
 import * as prettier from 'prettier';
 import { DeclarationOption, ParameterType } from 'typedoc';
 
-/**
- * Creates models for plugin options
- */
-
 export async function generateOptionsModels(docsConfig: DocsConfig) {
   const optionsConfig = await import(docsConfig.declarationsPath as string);
 
@@ -23,7 +19,7 @@ async function writeTypeDocDeclarations(
   docsConfig: DocsConfig,
   sortedOptionsConfig: any,
 ) {
-  const typedocDeclarationsFile = path.join(SRC_PATH, 'defs', 'typedoc.d.ts');
+  const typedocDeclarationsFile = path.join(SRC_PATH, '_typedoc.d.ts');
 
   const manuallyValidatedOptions = Object.entries(sortedOptionsConfig)
     .filter(
@@ -52,11 +48,25 @@ import { ManuallyValidatedOption } from 'typedoc'`);
   }`);
 
   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)}
+      export interface TranslatableStrings {
+        theme_default_value: [];
+        theme_default_type: [];
+        theme_description: [];
+        theme_event: [];
+        theme_extends: [];
+        theme_extended_by: [];
+        theme_member: [];
+        theme_member_plural: [];
+        theme_modifier: [];
+        theme_name: [];
+        theme_packages: [];
+        theme_type: [];
+        theme_value: [];
+        theme_version: [];
+    }
   }`);
   }
   out.push(`}`);
@@ -78,13 +88,16 @@ async function writeOptionsTypes(
       option.type === ParameterType.Mixed && option.defaultValue,
   );
 
-  const optionsOutput = `
-  // THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
-
+  const optionsOutput: string[] = [];
+  optionsOutput.push(`
   /**
    * Describes the options declared by the plugin.
    *
-   * @category Options
+   * @privateRemarks
+   *
+   * THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY
+   *
+   * @module
    */
   export interface PluginOptions {
     ${(Object.entries(sortedOptionsConfig) as any)
@@ -117,14 +130,14 @@ ${name}: ${getType(name, option, true)};`,
     `;
     })
     .join('\n')}
-  `;
+  `);
 
   const optionsModelFile = path.join(
     path.dirname(docsConfig.declarationsPath as string),
-    'option-types.ts',
+    'types.ts',
   );
 
-  const formatted = await prettier.format(optionsOutput, {
+  const formatted = await prettier.format(optionsOutput.join('\n\n'), {
     parser: 'typescript',
     singleQuote: true,
     trailingComma: 'all',
@@ -133,15 +146,6 @@ ${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.';
@@ -208,9 +212,22 @@ function getType(
       .map((value) => `"${value}"`)
       .join(' | ')}`;
   }
+  if (option.type === ParameterType.Object) {
+    const outType = `{${Object.keys(option.defaultValue as any)
+      .map((key) => `'${key}': ${getObjectType(name)};`)
+      .join('')}}`;
+    return isInterface ? outType : `ManuallyValidatedOption<${outType}>`;
+  }
   return 'any';
 }
 
+function getObjectType(name: string) {
+  if (name === 'reflectionFormats') {
+    return "'list'|'table'|'htmlTable'";
+  }
+  return 'string';
+}
+
 function capitalize(str: string) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }

docs/pages/api-docs/Class.MarkdownPageEvent.md

@@ -20,64 +20,81 @@ export function load(app: MarkdownApplication) {
 
 ### project
 
-> **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html)
+```ts
+project: ProjectReflection;
+```
 
-The project the renderer is currently processing.
+The [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) instance the renderer is currently processing.
 
 ***
 
 ### model
 
-> `readonly` **model**: `Model`
+```ts
+readonly model: Model;
+```
 
-The model that should be rendered on this page.
+The model that that is being rendered on this page.
+Either a [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) or [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html).
 
 ***
 
 ### url
 
-> **url**: `string`
+```ts
+url: string;
+```
 
-The url this page will be located at.
+The url `string` of the page.
 
 ***
 
 ### filename
 
-> **filename**: `string`
+```ts
+filename: string;
+```
 
-The filename the page will be written to.
+The complete `string` filename where the file will be written..
 
 ***
 
 ### contents?
 
-> `optional` **contents**: `string`
+```ts
+optional contents: string;
+```
 
-The final markdown content of this page.
+The final markdown `string` content of the page.
 
 Should be rendered by layout templates and can be modified by plugins.
 
 ***
 
 ### frontmatter?
 
-> `optional` **frontmatter**: `Record`\<`string`, `any`\>
+```ts
+optional frontmatter: Record<string, any>;
+```
 
 The frontmatter of this page represented as a key value object. This property can be utilised by other plugins.
 
 ## Events
 
 ### BEGIN
 
-> `static` `readonly` **BEGIN**: `"beginPage"` = `'beginPage'`
+```ts
+static readonly BEGIN: "beginPage" = 'beginPage';
+```
 
 Triggered before a document will be rendered.
 
 ***
 
 ### END
 
-> `static` `readonly` **END**: `"endPage"` = `'endPage'`
+```ts
+static readonly END: "endPage" = 'endPage';
+```
 
 Triggered after a document has been rendered, just before it is written to disc.

docs/pages/api-docs/Class.MarkdownRendererEvent.md

@@ -18,46 +18,58 @@ app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => {
 
 ### project
 
-> `readonly` **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html)
+```ts
+readonly project: ProjectReflection;
+```
 
 The project the renderer is currently processing.
 
 ***
 
 ### outputDirectory
 
-> `readonly` **outputDirectory**: `string`
+```ts
+readonly outputDirectory: string;
+```
 
 The path of the directory the documentation should be written to.
 
 ***
 
 ### urls?
 
-> `optional` **urls**: [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[]
+```ts
+optional urls: UrlMapping<Reflection>[];
+```
 
 A list of all pages that should be generated.
 
 ***
 
 ### navigation?
 
-> `optional` **navigation**: [`NavigationItem`](/api-docs/Interface.NavigationItem.md)[]
+```ts
+optional navigation: NavigationItem[];
+```
 
 The navigation structure of the project that can be utilised by plugins.
 
 ## Events
 
 ### BEGIN
 
-> `static` `readonly` **BEGIN**: `"beginRender"` = `'beginRender'`
+```ts
+static readonly BEGIN: "beginRender" = 'beginRender';
+```
 
 Triggered before the renderer starts rendering a project.
 
 ***
 
 ### END
 
-> `static` `readonly` **END**: `"endRender"` = `'endRender'`
+```ts
+static readonly END: "endRender" = 'endRender';
+```
 
 Triggered after the renderer has written all documents.