TechDocs: Generator can be given a pre-created output directory

TechDocs Generator uses a temporary directory to store the generated files. But with techdocs-cli, the generator needs to output in a fixed directory.

Also, make parsedLocationAnnotation optional since it is not a critical requirement for the generator.

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -66,24 +66,36 @@ export class TechdocsGenerator implements GeneratorBase {
   public async run({
     directory,
     dockerClient,
+    expectedResultDir,
     parsedLocationAnnotation,
   }: GeneratorRunOptions): Promise<GeneratorRunResult> {
-    const tmpdirPath = os.tmpdir();
-    // Fixes a problem with macOS returning a path that is a symlink
-    const tmpdirResolvedPath = fs.realpathSync(tmpdirPath);
-    const resultDir = fs.mkdtempSync(
-      path.join(tmpdirResolvedPath, 'techdocs-tmp-'),
-    );
+    // If provided with a directory to output the generated files in, use that directory.
+    // Else create a new temporary directory and return path.
+    let resultDir;
+    if (expectedResultDir) {
+      resultDir = expectedResultDir;
+      await fs.ensureDir(resultDir);
+    } else {
+      const tmpdirPath = os.tmpdir();
+      // Fixes a problem with macOS returning a path that is a symlink
+      const tmpdirResolvedPath = fs.realpathSync(tmpdirPath);
+      resultDir = fs.mkdtempSync(
+        path.join(tmpdirResolvedPath, 'techdocs-tmp-'),
+      );
+    }
+
     const [log, logStream] = createStream();
 
     // TODO: In future mkdocs.yml can be mkdocs.yaml. So, use a config variable here to find out
     // the correct file name.
     // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url
-    await patchMkdocsYmlPreBuild(
-      path.join(directory, 'mkdocs.yml'),
-      this.logger,
-      parsedLocationAnnotation,
-    );
+    if (parsedLocationAnnotation) {
+      await patchMkdocsYmlPreBuild(
+        path.join(directory, 'mkdocs.yml'),
+        this.logger,
+        parsedLocationAnnotation,
+      );
+    }
 
     try {
       switch (this.options.runGeneratorIn) {

packages/techdocs-common/src/stages/generate/types.ts

@@ -31,13 +31,15 @@ export type GeneratorRunResult = {
  *
  * @param {string} directory The directory of the uncompiled documentation, with the values from the frontend
  * @param {Docker} dockerClient A docker client to run any generator on top of your directory
+ * @param {string} expectedResultDir Optional directory to store generated docs in. Default: A newly created temporary directory.
  * @param {ParsedLocationAnnotation} parsedLocationAnnotation backstage.io/techdocs-ref annotation of an entity
  * @param {Writable} [logStream] A dedicated log stream
  */
 export type GeneratorRunOptions = {
   directory: string;
   dockerClient: Docker;
-  parsedLocationAnnotation: ParsedLocationAnnotation;
+  expectedResultDir?: string;
+  parsedLocationAnnotation?: ParsedLocationAnnotation;
   logStream?: Writable;
 };
 

packages/techdocs-common/src/stages/prepare/index.ts

@@ -17,4 +17,4 @@ export { DirectoryPreparer } from './dir';
 export { CommonGitPreparer } from './commonGit';
 export { UrlPreparer } from './url';
 export { Preparers } from './preparers';
-export type { PreparerBuilder, PreparerBase } from './types';
+export type { PreparerBuilder, PreparerBase, RemoteProtocol } from './types';