Merge remote-tracking branch 'origin/dev'

Author: Gerrit0

CHANGELOG.md

@@ -9,6 +9,8 @@ title: Changelog
 -   `@includeCode` and `@inline` can now inject parts of files using region
     names or line numbers, #2816.
 -   Introduced `ja` translation options, deprecated `jp` in favor of `ja`, #2843.
+-   Improved TypeDoc's `--watch` option to support watching files not caught by
+    TypeScript's watch mode, #2675.
 -   The `@inline` tag now works in more places for generic types.
 -   Visibility filters now consider individual signatures, #2846.
 
@@ -19,9 +21,12 @@ title: Changelog
 -   Fixed an issue with `@class` incorrectly handling mapped types, #2842.
 -   TypeDoc will now consider symbols to be external only if all of their declarations are external
     so that declaration merged members with global symbols can be documented, #2844.
+-   Fixed an issue where TypeDoc would constantly rebuild, #2844.
+-   Fixed an issue where the dropdown arrow in the index group would not respect the state of the dropdown, #2845.
 
 ### Thanks!
 
+-   @pjeby
 -   @shawninder
 -   @tats-u
 -   @XeroAlpha

bin/typedoc

@@ -1,5 +1,24 @@
 #!/usr/bin/env node
 //@ts-check
 
-/* eslint-disable @typescript-eslint/no-var-requires */
-import("../dist/lib/cli.js");
+const { fork } = require("child_process");
+
+function main() {
+    fork(__dirname + "/../dist/lib/cli.js", process.argv.slice(2), {
+        stdio: "inherit",
+    }).on("exit", (code) => {
+        // Watch restart required? Fork a new child
+        if (code === 7) {
+            // Set an environment variable to ensure we continue watching
+            // Otherwise, the watch might stop unexpectedly if the watch
+            // option was set in a config file originally, and change to false
+            // later, causing a restart
+            process.env["TYPEDOC_FORCE_WATCH"] = "1";
+            main();
+        } else {
+            process.exit(code || 0);
+        }
+    });
+}
+
+main();

site/options/other.md

@@ -13,9 +13,12 @@ $ typedoc --watch
 Use TypeScript's incremental compiler to watch source files for changes and
 build the docs on change. May be combined with `--emit`.
 
-> [!note] This mode will only detect changes to files watched by the TypeScript
-> compiler. Changes to other files (`README.md`, imported files with `@include` or
-> `@includeCode`) will not cause a rebuild.
+This mode detects changes to project documents, readme, custom JS/CSS,
+configuration files, files imported by `@include`/`@includeCode`, and any
+files explicitly registered by plugins as needing to be watched, as well
+as all your TypeScript source files.
+
+Watch mode is not supported with `entryPointStrategy` set to `packages` or `merge`.
 
 ## preserveWatchOutput
 

site/tags/include.md

@@ -44,6 +44,13 @@ For example:
 {@includeCode ../../example/src/enums.ts#simpleEnum}
 ```
 
+Multiple regions may be specified, separated by commas. If multiple regions are
+specified, TypeDoc will combine them into a single code block.
+
+```md
+{@includeCode file.ts#region1,region2}
+```
+
 Regions are specified in the files themselves via comments.
 
 In TypeScript for example, the following would be a valid region:

src/lib/application.ts

@@ -231,7 +231,9 @@ export class Application extends AbstractComponent<
         readers.forEach((r) => app.options.addReader(r));
         app.options.reset();
         app.setOptions(options, /* reportErrors */ false);
-        await app.options.read(new Logger());
+        await app.options.read(new Logger(), undefined, (path) =>
+            app.watchConfigFile(path),
+        );
         app.logger.level = app.options.getValue("logLevel");
 
         await loadPlugins(app, app.options.getValue("plugin"));
@@ -265,7 +267,9 @@ export class Application extends AbstractComponent<
     private async _bootstrap(options: Partial<TypeDocOptions>) {
         this.options.reset();
         this.setOptions(options, /* reportErrors */ false);
-        await this.options.read(this.logger);
+        await this.options.read(this.logger, undefined, (path) =>
+            this.watchConfigFile(path),
+        );
         this.setOptions(options);
         this.logger.level = this.options.getValue("logLevel");
         for (const [lang, locales] of Object.entries(
@@ -286,17 +290,22 @@ export class Application extends AbstractComponent<
         if (!this.internationalization.hasTranslations(this.lang)) {
             // Not internationalized as by definition we don't know what to include here.
             this.logger.warn(
-                `Options specified "${this.lang}" as the language to use, but TypeDoc does not support it.` as TranslatedString,
+                `Options specified "${this.lang}" as the language to use, but TypeDoc cannot provide translations for it.` as TranslatedString,
             );
             this.logger.info(
-                ("The supported languages are:\n\t" +
+                ("The languages that translations are available for are:\n\t" +
                     this.internationalization
                         .getSupportedLanguages()
                         .join("\n\t")) as TranslatedString,
             );
             this.logger.info(
                 "You can define/override local locales with the `locales` option, or contribute them to TypeDoc!" as TranslatedString,
             );
+        } else if (this.lang === "jp") {
+            this.logger.warn(
+                // Only Japanese see this. Meaning: "jp" is going to be removed in the future. Please designate "ja" instead.
+                "「jp」は将来削除されます。代わりに「ja」を指定してください。" as TranslatedString,
+            );
         }
 
         if (
@@ -425,9 +434,49 @@ export class Application extends AbstractComponent<
         return project;
     }
 
-    public convertAndWatch(
+    private watchers = new Map<string, ts.FileWatcher>();
+    private _watchFile?: (path: string, shouldRestart?: boolean) => void;
+    private criticalFiles = new Set<string>();
+
+    private clearWatches() {
+        this.watchers.forEach((w) => w.close());
+        this.watchers.clear();
+    }
+
+    private watchConfigFile(path: string) {
+        this.criticalFiles.add(path);
+    }
+
+    /**
+     * Register that the current build depends on a file, so that in watch mode
+     * the build will be repeated.  Has no effect if a watch build is not
+     * running, or if the file has already been registered.
+     *
+     * @param path The file to watch.  It does not need to exist, and you should
+     * in fact register files you look for, but which do not exist, so that if
+     * they are created the build will re-run.  (e.g. if you look through a list
+     * of 5 possibilities and find the third, you should register the first 3.)
+     *
+     * @param shouldRestart Should the build be completely restarted?  (This is
+     * normally only used for configuration files -- i.e. files whose contents
+     * determine how conversion, rendering, or compiling will be done, as
+     * opposed to files that are only read *during* the conversion or
+     * rendering.)
+     */
+    public watchFile(path: string, shouldRestart = false) {
+        this._watchFile?.(path, shouldRestart);
+    }
+
+    /**
+     * Run a convert / watch process.
+     *
+     * @param success Callback to run after each convert, receiving the project
+     * @returns True if the watch process should be restarted due to a
+     * configuration change, false for an options error
+     */
+    public async convertAndWatch(
         success: (project: ProjectReflection) => Promise<void>,
-    ): void {
+    ): Promise<boolean> {
         if (
             !this.options.getValue("preserveWatchOutput") &&
             this.logger instanceof ConsoleLogger
@@ -459,7 +508,7 @@ export class Application extends AbstractComponent<
         // have reported in the first time... just error out for now. I'm not convinced anyone will actually notice.
         if (this.options.getFileNames().length === 0) {
             this.logger.error(this.i18n.solution_not_supported_in_watch_mode());
-            return;
+            return false;
         }
 
         // Support for packages mode is currently unimplemented
@@ -468,7 +517,7 @@ export class Application extends AbstractComponent<
             this.entryPointStrategy !== EntryPointStrategy.Expand
         ) {
             this.logger.error(this.i18n.strategy_not_supported_in_watch_mode());
-            return;
+            return false;
         }
 
         const tsconfigFile =
@@ -481,7 +530,7 @@ export class Application extends AbstractComponent<
 
         const host = ts.createWatchCompilerHost(
             tsconfigFile,
-            {},
+            this.options.fixCompilerOptions({}),
             ts.sys,
             ts.createEmitAndSemanticDiagnosticsBuilderProgram,
             (diagnostic) => this.logger.diagnostic(diagnostic),
@@ -506,16 +555,69 @@ export class Application extends AbstractComponent<
 
         let successFinished = true;
         let currentProgram: ts.Program | undefined;
+        let lastProgram = currentProgram;
+        let restarting = false;
+
+        this._watchFile = (path: string, shouldRestart = false) => {
+            this.logger.verbose(
+                `Watching ${nicePath(path)}, shouldRestart=${shouldRestart}`,
+            );
+            if (this.watchers.has(path)) return;
+            this.watchers.set(
+                path,
+                host.watchFile(
+                    path,
+                    (file) => {
+                        if (shouldRestart) {
+                            restartMain(file);
+                        } else if (!currentProgram) {
+                            currentProgram = lastProgram;
+                            this.logger.info(
+                                this.i18n.file_0_changed_rebuilding(
+                                    nicePath(file),
+                                ),
+                            );
+                        }
+                        if (successFinished) runSuccess();
+                    },
+                    2000,
+                ),
+            );
+        };
+
+        /** resolver for the returned promise  */
+        let exitWatch: (restart: boolean) => unknown;
+        const restartMain = (file: string) => {
+            if (restarting) return;
+            this.logger.info(
+                this.i18n.file_0_changed_restarting(nicePath(file)),
+            );
+            restarting = true;
+            currentProgram = undefined;
+            this.clearWatches();
+            tsWatcher.close();
+        };
 
         const runSuccess = () => {
+            if (restarting && successFinished) {
+                successFinished = false;
+                exitWatch(true);
+                return;
+            }
+
             if (!currentProgram) {
                 return;
             }
 
             if (successFinished) {
-                if (this.options.getValue("emit") === "both") {
+                if (
+                    this.options.getValue("emit") === "both" &&
+                    currentProgram !== lastProgram
+                ) {
                     currentProgram.emit();
                 }
+                // Save for possible re-run due to non-.ts file change
+                lastProgram = currentProgram;
 
                 this.logger.resetErrors();
                 this.logger.resetWarnings();
@@ -527,6 +629,10 @@ export class Application extends AbstractComponent<
                 if (!entryPoints) {
                     return;
                 }
+                this.clearWatches();
+                this.criticalFiles.forEach((path) =>
+                    this.watchFile(path, true),
+                );
                 const project = this.converter.convert(entryPoints);
                 currentProgram = undefined;
                 successFinished = false;
@@ -537,40 +643,24 @@ export class Application extends AbstractComponent<
             }
         };
 
-        const origCreateProgram = host.createProgram;
-        host.createProgram = (
-            rootNames,
-            options,
-            host,
-            oldProgram,
-            configDiagnostics,
-            references,
-        ) => {
-            // If we always do this, we'll get a crash the second time a program is created.
-            if (rootNames !== undefined) {
-                options = this.options.fixCompilerOptions(options || {});
-            }
-
-            return origCreateProgram(
-                rootNames,
-                options,
-                host,
-                oldProgram,
-                configDiagnostics,
-                references,
-            );
-        };
-
         const origAfterProgramCreate = host.afterProgramCreate;
         host.afterProgramCreate = (program) => {
-            if (ts.getPreEmitDiagnostics(program.getProgram()).length === 0) {
+            if (
+                !restarting &&
+                ts.getPreEmitDiagnostics(program.getProgram()).length === 0
+            ) {
                 currentProgram = program.getProgram();
                 runSuccess();
             }
             origAfterProgramCreate?.(program);
         };
 
-        ts.createWatchProgram(host);
+        const tsWatcher = ts.createWatchProgram(host);
+
+        // Don't return to caller until the watch needs to restart
+        return await new Promise((res) => {
+            exitWatch = res;
+        });
     }
 
     validate(project: ProjectReflection) {

src/lib/cli.ts

@@ -32,8 +32,8 @@ async function main() {
         if (exitCode !== ExitCodes.Watching) {
             app.logger.verbose(`Full run took ${Date.now() - start}ms`);
             logRunSummary(app.logger);
-            process.exit(exitCode);
         }
+        process.exit(exitCode);
     } catch (error) {
         console.error("TypeDoc exiting with unexpected error:");
         console.error(error);
@@ -72,12 +72,13 @@ async function run(app: td.Application) {
         return ExitCodes.OptionError;
     }
 
-    if (app.options.getValue("watch")) {
-        app.convertAndWatch(async (project) => {
+    if (app.options.getValue("watch") || process.env["TYPEDOC_FORCE_WATCH"]) {
+        const continueWatching = await app.convertAndWatch(async (project) => {
             app.validate(project);
             await app.generateOutputs(project);
         });
-        return ExitCodes.Watching;
+
+        return continueWatching ? ExitCodes.Watching : ExitCodes.OptionError;
     }
 
     const project = await app.convert();

src/lib/converter/converter.ts

@@ -688,6 +688,7 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
             frontmatter,
         );
 
+        this.application.watchFile(file.fileName);
         parent.addChild(docRefl);
         parent.project.registerReflection(docRefl, undefined, file.fileName);
         this.trigger(ConverterEvents.CREATE_DOCUMENT, undefined, docRefl);