From c65dc26c105f4437e7b3527f9a798692fa7e49b8 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Wed, 6 Jan 2021 10:59:16 +0100
Subject: [PATCH] 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.
---
 .../src/stages/generate/techdocs.ts           | 34 +++++++++++++------
 .../src/stages/generate/types.ts              |  4 ++-
 .../src/stages/prepare/index.ts               |  2 +-
 3 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/packages/techdocs-common/src/stages/generate/techdocs.ts b/packages/techdocs-common/src/stages/generate/techdocs.ts
index faefd8ac16..bdecb9cbf3 100644
--- a/packages/techdocs-common/src/stages/generate/techdocs.ts
+++ b/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) {
diff --git a/packages/techdocs-common/src/stages/generate/types.ts b/packages/techdocs-common/src/stages/generate/types.ts
index 65e411c3aa..8a3e68392b 100644
--- a/packages/techdocs-common/src/stages/generate/types.ts
+++ b/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;
 };
 
diff --git a/packages/techdocs-common/src/stages/prepare/index.ts b/packages/techdocs-common/src/stages/prepare/index.ts
index 6c73725a3a..dcb178bafa 100644
--- a/packages/techdocs-common/src/stages/prepare/index.ts
+++ b/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';