Merge pull request #6341 from SDA-SE/feat/techdocs-build-logs

packages/techdocs-common/api-report.md

@@ -55,6 +55,16 @@ export type GeneratorBuilder = {
   get(entity: Entity): GeneratorBase;
 };
 
+// @public
+export type GeneratorRunOptions = {
+  inputDir: string;
+  outputDir: string;
+  parsedLocationAnnotation?: ParsedLocationAnnotation;
+  etag?: string;
+  logger: Logger_2;
+  logStream?: Writable;
+};
+
 // @public (undocumented)
 export class Generators implements GeneratorBuilder {
   // (undocumented)
@@ -232,6 +242,8 @@ export class TechdocsGenerator implements GeneratorBase {
     outputDir,
     parsedLocationAnnotation,
     etag,
+    logger: childLogger,
+    logStream,
   }: GeneratorRunOptions): Promise<void>;
 }
 

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

@@ -15,4 +15,8 @@
  */
 export { TechdocsGenerator } from './techdocs';
 export { Generators } from './generators';
-export type { GeneratorBuilder, GeneratorBase } from './types';
+export type {
+  GeneratorBuilder,
+  GeneratorBase,
+  GeneratorRunOptions,
+} from './types';

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

@@ -17,7 +17,6 @@
 import { ContainerRunner } from '@backstage/backend-common';
 import { Config } from '@backstage/config';
 import path from 'path';
-import { PassThrough } from 'stream';
 import { Logger } from 'winston';
 import {
   addBuildTimestampMetadata,
@@ -35,18 +34,6 @@ type TechdocsGeneratorOptions = {
   runGeneratorIn: string;
 };
 
-const createStream = (): [string[], PassThrough] => {
-  const log = [] as Array<string>;
-
-  const stream = new PassThrough();
-  stream.on('data', chunk => {
-    const textValue = chunk.toString().trim();
-    if (textValue?.length > 1) log.push(textValue);
-  });
-
-  return [log, stream];
-};
-
 export class TechdocsGenerator implements GeneratorBase {
   private readonly logger: Logger;
   private readonly containerRunner: ContainerRunner;
@@ -74,9 +61,9 @@ export class TechdocsGenerator implements GeneratorBase {
     outputDir,
     parsedLocationAnnotation,
     etag,
+    logger: childLogger,
+    logStream,
   }: GeneratorRunOptions): Promise<void> {
-    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
@@ -84,7 +71,7 @@ export class TechdocsGenerator implements GeneratorBase {
     if (parsedLocationAnnotation) {
       await patchMkdocsYmlPreBuild(
         mkdocsYmlPath,
-        this.logger,
+        childLogger,
         parsedLocationAnnotation,
       );
     }
@@ -108,7 +95,7 @@ export class TechdocsGenerator implements GeneratorBase {
             },
             logStream,
           });
-          this.logger.info(
+          childLogger.info(
             `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,
           );
           break;
@@ -123,7 +110,7 @@ export class TechdocsGenerator implements GeneratorBase {
             // write to, otherwise they will just fail trying to write to /
             envVars: { HOME: '/tmp' },
           });
-          this.logger.info(
+          childLogger.info(
             `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,
           );
           break;
@@ -136,7 +123,6 @@ export class TechdocsGenerator implements GeneratorBase {
       this.logger.debug(
         `Failed to generate docs from ${inputDir} into ${outputDir}`,
       );
-      this.logger.error(`Build failed with error: ${log}`);
       throw new Error(
         `Failed to generate docs from ${inputDir} into ${outputDir} with error ${error.message}`,
       );
@@ -150,7 +136,7 @@ export class TechdocsGenerator implements GeneratorBase {
     // Creates techdocs_metadata.json if file does not exist.
     await addBuildTimestampMetadata(
       path.join(outputDir, 'techdocs_metadata.json'),
-      this.logger,
+      childLogger,
     );
 
     // Add etag of the prepared tree to techdocs_metadata.json

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

@@ -13,8 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 import { Entity } from '@backstage/catalog-model';
 import { Writable } from 'stream';
+import { Logger } from 'winston';
 import { ParsedLocationAnnotation } from '../../helpers';
 
 /**
@@ -24,13 +26,15 @@ import { ParsedLocationAnnotation } from '../../helpers';
  * @param {string} outputDir Directory to store generated docs in. Usually - a newly created temporary directory.
  * @param {ParsedLocationAnnotation} parsedLocationAnnotation backstage.io/techdocs-ref annotation of an entity
  * @param {string} etag A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored in techdocs_metadata.json.
- * @param {Writable} [logStream] A dedicated log stream
+ * @param {Logger} [logger] A logger that forwards the messages to the caller to be displayed outside of the backend.
+ * @param {Writable} [logStream] A log stream that can send raw log messages to the caller to be displayed outside of the backend..
  */
 export type GeneratorRunOptions = {
   inputDir: string;
   outputDir: string;
   parsedLocationAnnotation?: ParsedLocationAnnotation;
   etag?: string;
+  logger: Logger;
   logStream?: Writable;
 };