refactor: simplify output location, updated instructions, allow TypeDoc config options to be passed

huwshimi · huwshimi · commit cfb9ed1ac018 · 2024-11-19T09:24:06.000+11:00
diff --git a/docs/src/pages/reference/configuration/output.md b/docs/src/pages/reference/configuration/output.md
@@ -394,13 +394,15 @@ Default Value: `false`.
 
 Will generate API docs using [TypeDoc](https://typedoc.org/). by default these docs will be in Markdown format.
 
-TypeDoc can be configured by creating a config file e.g. `typedoc.config.mjs` in your project root (see the [config docs](https://typedoc.org/options/configuration/#options) for a full list of supported file names) or by passing a config filename to the `config` option below.
+TypeDoc can be configured by passing the [options](https://typedoc.org/options/) to the `docs` object or by creating a config file e.g. `typedoc.config.mjs` in your project root (see the [config docs](https://typedoc.org/options/configuration/#options) for a full list of supported file names) or by passing a config filename to the `configPath` option below.
 
 See the TypeDoc [configuration documentation](https://typedoc.org/options/) for more details.
 
 The `docs` option can take some properties to customize the generation if you set it to an object. If you set it to `true`, the default options will be used.
 
-#### config
+When no output directory destination is specified in `config`, the file will be output to the `docs` directory by default.
+
+#### configPath
 
 Type: `String`.
 
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -24,7 +24,8 @@
     "@types/lodash.uniq": "^4.5.9",
     "@types/lodash.uniqby": "^4.7.9",
     "@types/lodash.uniqwith": "^4.5.9",
-    "@types/micromatch": "^4.0.9"
+    "@types/micromatch": "^4.0.9",
+    "typedoc": "0.26.11"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -12,6 +12,7 @@ import type {
 } from 'openapi3-ts/oas30';
 // @ts-ignore // FIXME when running `yarn test` getting `orval:test: ../core/src/types.ts(12,34): error TS7016: Could not find a declaration file for module 'swagger2openapi'. '/home/maxim/orval/node_modules/swagger2openapi/index.js' implicitly has an 'any' type.`
 import type swagger2openapi from 'swagger2openapi';
+import { TypeDocOptions } from 'typedoc';
 
 export interface Options {
   output?: string | OutputOptions;
@@ -242,8 +243,8 @@ export const OutputMode = {
 export type OutputMode = (typeof OutputMode)[keyof typeof OutputMode];
 
 export type OutputDocsOptions = {
-  config: string;
-};
+  configPath?: string;
+} & Partial<TypeDocOptions>;
 
 // TODO: add support for other mock types (like cypress or playwright)
 export const OutputMockType = {
diff --git a/packages/orval/src/write-specs.ts b/packages/orval/src/write-specs.ts
@@ -18,7 +18,7 @@ import {
 import chalk from 'chalk';
 import execa from 'execa';
 import fs from 'fs-extra';
-import { Application } from 'typedoc';
+import { Application, TypeDocOptions } from 'typedoc';
 import uniq from 'lodash.uniq';
 import { InfoObject } from 'openapi3-ts/oas30';
 import { executeHook } from './utils';
@@ -201,12 +201,18 @@ export const writeSpecs = async (
 
   if (output.docs) {
     try {
+      let config: Partial<TypeDocOptions> = {};
+      let configPath: string | null = null;
+      if (typeof output.docs === 'object') {
+        ({ configPath = null, ...config } = output.docs);
+        if (configPath) {
+          config.options = configPath;
+        }
+      }
       const app = await Application.bootstrapWithPlugins({
         entryPoints: paths,
         // Set the custom config location if it has been provided.
-        ...(typeof output.docs === 'object'
-          ? { options: output.docs.config }
-          : {}),
+        ...config,
         plugin: ['typedoc-plugin-markdown'],
       });
       // Set defaults if the have not been provided by the external config.
@@ -218,19 +224,7 @@ export const writeSpecs = async (
       }
       const project = await app.convert();
       if (project) {
-        let out = 'docs';
-        if (app.options.isSet('out')) {
-          // Use the output location if it has been set in the external config.
-          out = app.options.getValue('out');
-        } else if (output.workspace) {
-          // Generate the docs in the workspace.
-          out = upath.join(output.workspace, 'docs');
-        } else if (output.target) {
-          const base = upath.dirname(output.target);
-          // Generate the docs along side the output target.
-          out = upath.join(base, 'docs');
-        }
-        await app.generateDocs(project, out);
+        await app.generateDocs(project, app.options.getValue('out'));
       } else {
         throw new Error('TypeDoc not initialised');
       }
