refactor(techdocs-common): clean up generator api

Signed-off-by: Camila Belo <camilaibs@gmail.com>

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

@@ -26,9 +26,18 @@ import {
   SupportedGeneratorKey,
 } from './types';
 
+/**
+ * Collection of docs generators
+ * @public
+ */
 export class Generators implements GeneratorBuilder {
   private generatorMap = new Map<SupportedGeneratorKey, GeneratorBase>();
 
+  /**
+   * Returns a generators instance containing a generator for Tech Docs
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the Tech Docs generator
+   */
   static async fromConfig(
     config: Config,
     options: { logger: Logger; containerRunner: ContainerRunner },
@@ -41,10 +50,19 @@ export class Generators implements GeneratorBuilder {
     return generators;
   }
 
+  /**
+   * Register a generator in the generators collection
+   * @param generatorKey - Unique identifier for the generator
+   * @param generator - The generator instance to register
+   */
   register(generatorKey: SupportedGeneratorKey, generator: GeneratorBase) {
     this.generatorMap.set(generatorKey, generator);
   }
 
+  /**
+   * Returns the generator for a given Tech Docs entity
+   * @param entity - A Tech Docs entity instance
+   */
   get(entity: Entity): GeneratorBase {
     const generatorKey = getGeneratorKey(entity);
     const generator = this.generatorMap.get(generatorKey);

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

@@ -16,7 +16,9 @@
 export { TechdocsGenerator } from './techdocs';
 export { Generators } from './generators';
 export type {
-  GeneratorBuilder,
   GeneratorBase,
+  GeneratorBuilder,
+  GeneratorFactory,
   GeneratorRunOptions,
+  SupportedGeneratorKey,
 } from './types';

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

@@ -38,7 +38,12 @@ import {
   GeneratorRunOptions,
 } from './types';
 import { ForwardedError } from '@backstage/errors';
+import { GeneratorFactory } from './types';
 
+/**
+ * Generates documentation files
+ * @public
+ */
 export class TechdocsGenerator implements GeneratorBase {
   /**
    * The default docker image (and version) used to generate content. Public
@@ -50,10 +55,12 @@ export class TechdocsGenerator implements GeneratorBase {
   private readonly options: GeneratorConfig;
   private readonly scmIntegrations: ScmIntegrationRegistry;
 
-  static fromConfig(
-    config: Config,
-    options: { containerRunner: ContainerRunner; logger: Logger },
-  ) {
+  /**
+   * Returns a instance of Tech Docs generator
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the generator
+   */
+  static fromConfig(config: Config, options: GeneratorFactory) {
     const { containerRunner, logger } = options;
     const scmIntegrations = ScmIntegrations.fromConfig(config);
     return new TechdocsGenerator({
@@ -76,6 +83,7 @@ export class TechdocsGenerator implements GeneratorBase {
     this.scmIntegrations = options.scmIntegrations;
   }
 
+  /** {@inheritDoc GeneratorBase.run} */
   public async run(options: GeneratorRunOptions): Promise<void> {
     const {
       inputDir,

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

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { ContainerRunner } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { Writable } from 'stream';
 import { Logger } from 'winston';
@@ -22,6 +23,15 @@ import { ParsedLocationAnnotation } from '../../helpers';
 // Determines where the generator will be run
 export type GeneratorRunInType = 'docker' | 'local';
 
+/**
+ * Options for building generators
+ * @public
+ */
+export type GeneratorFactory = {
+  containerRunner: ContainerRunner;
+  logger: Logger;
+};
+
 /**
  * The techdocs generator configurations options.
  */
@@ -51,18 +61,27 @@ export type GeneratorRunOptions = {
   logStream?: Writable;
 };
 
+/**
+ * Generates documentation files
+ * @public
+ */
 export type GeneratorBase = {
-  // Runs the generator with the values
+  /**
+   * Runs the generator with the values
+   * @public
+   */
   run(opts: GeneratorRunOptions): Promise<void>;
 };
 
 /**
  * List of supported generator options
+ * @public
  */
 export type SupportedGeneratorKey = 'techdocs' | string;
 
 /**
  * The generator builder holds the generator ready for run time
+ * @public
  */
 export type GeneratorBuilder = {
   register(protocol: SupportedGeneratorKey, generator: GeneratorBase): void;

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

@@ -26,18 +26,43 @@ import { Logger } from 'winston';
 import { parseReferenceAnnotation, transformDirLocation } from '../../helpers';
 import { PreparerBase, PreparerResponse } from './types';
 
+export type DirectoryPreparerOptions = {
+  config: Config;
+  reader: UrlReader;
+};
+
+export type PreparerOptions = { logger?: Logger; etag?: string };
+
+/**
+ * Prepares files before building documentation
+ *
+ * @public
+ */
 export class DirectoryPreparer implements PreparerBase {
   private readonly scmIntegrations: ScmIntegrationRegistry;
   private readonly reader: UrlReader;
 
-  constructor(config: Config, _logger: Logger, reader: UrlReader) {
+  /**
+   * @deprecated use static fromConfig method instead.
+   */
+  constructor(config: Config, _logger: Logger | null, reader: UrlReader) {
     this.reader = reader;
     this.scmIntegrations = ScmIntegrations.fromConfig(config);
   }
 
+  static fromConfig(options: DirectoryPreparerOptions): DirectoryPreparer {
+    return new DirectoryPreparer(options.config, null, options.reader);
+  }
+
+  /**
+   *
+   * @param entity - The parts of the format that's common to all versions/kinds of entity
+   * @param options - Optional logger and etag
+   * @returns
+   */
   async prepare(
     entity: Entity,
-    options?: { logger?: Logger; etag?: string },
+    options?: PreparerOptions,
   ): Promise<PreparerResponse> {
     const annotation = parseReferenceAnnotation(
       'backstage.io/techdocs-ref',