please consider including watch example in node module code snippet

[hesxenon]

Search Terms

watch, node, api

Problem

I'm having trouble figuring out how to get watch mode up and running with the node module API. I'd like some docs on this and I think that would best fit in this section.

Suggested Solution

I am currently trying to do it like this:

app.convertAndWatch(async (project) => {
  await app.generateDocs(project, config.out);
});

but doing so does not work as expected when it comes to projectdocuments - changing them removes them (might be a bug?).

[Gerrit0]

Watch mode isn't as trivial as calling that one function unfortunately, because changes to the typedoc configuration may require completely restarting the building process. I'd really recommend just calling the CLI over re-implementing the terrible fork loop that TypeDoc's bin script has to use.

Your change to project documents is almost certainly done by changing a config file, which is one of the cases where the promise returned by convertAndWatch will resolve with true, indicating that the process should be restarted.

typedoc/bin/typedoc

Lines 6 to 22 in 831c9f4

	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);
	}
	});
	}

typedoc/src/lib/cli.ts

Lines 76 to 83 in 831c9f4

	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 continueWatching ? ExitCodes.Watching : ExitCodes.OptionError;
	}

[hesxenon]

ah, I see...

I'm actually not changing configs but markdown files configured with projectDocuments.

I've tried to create a sort of simple process to just watch the docs and host them within a single process, but I'll probably do that by spawning a CLI process then.

Maybe it would be a good idea though to list some use cases where the API is actually useful then? Because from my pov it doesn't look like you should use it then?

[Gerrit0]

You could do that with the API, it just won't be as clean as you'd want. I know docusaurus has a watch mode and there is a plugin which integrates typedoc with it, I don't know how it works, but it's definitely possible