Add support for packageOptions

Resolves #2523

Author: Gerrit0

CHANGELOG.md

@@ -38,6 +38,7 @@
 -   Added new `--projectDocuments` option to specify additional Markdown documents to be included in the generated site #247, #1870, #2288, #2565.
 -   TypeDoc now has the architecture in place to support localization. No languages besides English
     are currently shipped in the package, but it is now possible to add support for additional languages, #2475.
+-   Added support for a `packageOptions` object which specifies options that should be applied to each entry point when running with `--entryPointStrategy packages`, #2523.
 -   `--hostedBaseUrl` will now be used to generate a `<link rel="canonical">` element in the project root page, #2550.
 -   New option, `--customFooterHtml` to add custom HTML to the generated page footer, #2559.
 -   Added three new sort strategies `documents-first`, `documents-last`, and `alphabetical-ignoring-documents` to order markdown documents.

src/lib/application.ts

@@ -627,7 +627,20 @@ export class Application extends ChildableComponent<
         // Generate a json file for each package
         for (const dir of packageDirs) {
             this.logger.verbose(`Reading project at ${nicePath(dir)}`);
-            const opts = origOptions.copyForPackage(dir);
+            let opts: Options;
+            try {
+                opts = origOptions.copyForPackage(dir);
+            } catch (error) {
+                ok(error instanceof Error);
+                this.logger.error(error.message as TranslatedString);
+                this.logger.info(
+                    this.i18n.previous_error_occurred_when_reading_options_for_0(
+                        nicePath(dir),
+                    ),
+                );
+                continue;
+            }
+
             await opts.read(this.logger, dir);
             // Invalid links should only be reported after everything has been merged.
             opts.setValue("validation", { invalidLink: false });

src/lib/internationalization/translatable.ts

@@ -36,6 +36,8 @@ export const translatable = {
         "Failed to find any packages, ensure you have provided at least one directory as an entry point containing package.json",
     nested_packages_unsupported_0:
         "Project at {0} has entryPointStrategy set to packages, but nested packages are not supported.",
+    previous_error_occurred_when_reading_options_for_0:
+        "The previous error occurred when reading options for the package at {0}",
     converting_project_at_0: "Converting project at {0}",
     failed_to_convert_packages:
         "Failed to convert one or more packages, result will not be merged together.",
@@ -173,6 +175,8 @@ export const translatable = {
         "Sets the language to be used in generation and in TypeDoc's messages.",
     help_locales:
         "Add translations for a specified locale. This option is primarily intended to be used as a stopgap while waiting for official locale support to be added to TypeDoc.",
+    help_packageOptions:
+        "Set options which will be set within each package when entryPointStrategy is set to packages.",
 
     help_entryPoints: "The entry points of your documentation.",
     help_entryPointStrategy:

src/lib/utils/options/declaration.ts

@@ -99,6 +99,7 @@ export interface TypeDocOptionMap {
     plugin: string[];
     lang: string;
     locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
+    packageOptions: ManuallyValidatedOption<TypeDocOptions>;
 
     // Input
     entryPoints: string[];

src/lib/utils/options/options.ts

@@ -119,6 +119,12 @@ export class Options {
         options._declarations = new Map(this._declarations);
         options.reset();
 
+        for (const [key, val] of Object.entries(
+            this.getValue("packageOptions"),
+        )) {
+            options.setValue(key as any, val, packageDir);
+        }
+
         return options;
     }
 

src/lib/utils/options/sources/typedoc.ts

@@ -78,6 +78,20 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             }
         },
     });
+    options.addDeclaration({
+        name: "packageOptions",
+        help: (i18n) => i18n.help_packageOptions(),
+        type: ParameterType.Mixed,
+        configFileOnly: true,
+        defaultValue: {},
+        validate(value, i18n) {
+            if (!Validation.validate({}, value)) {
+                throw new Error(
+                    i18n.option_0_must_be_an_object("packageOptions"),
+                );
+            }
+        },
+    });
 
     ///////////////////////////
     ////// Input Options //////