Merge pull request #9718 from backstage/cleanup-techdocs-commons

[TechDocs] clean up techdocs-common
2022-02-24 10:29:06 +01:00
parent 8cf64c4ec7 13ef228d03
commit 6427f1ddf8
16 changed files with 361 additions and 151 deletions
@@ -0,0 +1,5 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Clean up the API interface for TechDocs common library.
@@ -17,38 +17,37 @@ import { ScmIntegrationRegistry } from '@backstage/integration';
 import { UrlReader } from '@backstage/backend-common';
 import { Writable } from 'stream';

-// Warning: (ae-missing-release-tag) "DirectoryPreparer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class DirectoryPreparer implements PreparerBase {
-  constructor(config: Config, _logger: Logger_2, reader: UrlReader);
-  // Warning: (ae-forgotten-export) The symbol "PreparerResponse" needs to be exported by the entry point index.d.ts
-  //
-  // (undocumented)
-  prepare(
-    entity: Entity,
-    options?: {
-      logger?: Logger_2;
-      etag?: string;
-    },
-  ): Promise<PreparerResponse>;
+  // @deprecated
+  constructor(config: Config, _logger: Logger_2 | null, reader: UrlReader);
+  static fromConfig(
+    config: Config,
+    { logger, reader }: PreparerConfig,
+  ): DirectoryPreparer;
+  prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 }

-// Warning: (ae-missing-release-tag) "GeneratorBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type ETag = string;
+
+// @public
 export type GeneratorBase = {
  run(opts: GeneratorRunOptions): Promise<void>;
 };

-// Warning: (ae-missing-release-tag) "GeneratorBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type GeneratorBuilder = {
  register(protocol: SupportedGeneratorKey, generator: GeneratorBase): void;
  get(entity: Entity): GeneratorBase;
 };

+// @public
+export type GeneratorOptions = {
+  containerRunner: ContainerRunner;
+  logger: Logger_2;
+};
+
 // @public
 export type GeneratorRunOptions = {
  inputDir: string;
@@ -59,11 +58,8 @@ export type GeneratorRunOptions = {
  logStream?: Writable;
 };

-// Warning: (ae-missing-release-tag) "Generators" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class Generators implements GeneratorBuilder {
-  // (undocumented)
  static fromConfig(
    config: Config,
    options: {
@@ -71,15 +67,11 @@ export class Generators implements GeneratorBuilder {
      containerRunner: ContainerRunner;
    },
  ): Promise<GeneratorBuilder>;
-  // (undocumented)
  get(entity: Entity): GeneratorBase;
-  // (undocumented)
  register(generatorKey: SupportedGeneratorKey, generator: GeneratorBase): void;
 }

-// Warning: (ae-missing-release-tag) "getDocFilesFromRepository" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const getDocFilesFromRepository: (
  reader: UrlReader,
  entity: Entity,
@@ -91,78 +83,74 @@ export const getDocFilesFromRepository: (
    | undefined,
 ) => Promise<PreparerResponse>;

-// Warning: (ae-missing-release-tag) "getLocationForEntity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const getLocationForEntity: (
  entity: Entity,
  scmIntegration: ScmIntegrationRegistry,
 ) => ParsedLocationAnnotation;

-// Warning: (ae-missing-release-tag) "ParsedLocationAnnotation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type MigrateRequest = {
+  removeOriginal?: boolean;
+  concurrency?: number;
+};
+
+// @public
 export type ParsedLocationAnnotation = {
  type: RemoteProtocol;
  target: string;
 };

-// Warning: (ae-missing-release-tag) "parseReferenceAnnotation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export const parseReferenceAnnotation: (
  annotationName: string,
  entity: Entity,
 ) => ParsedLocationAnnotation;

-// Warning: (ae-missing-release-tag) "PreparerBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type PreparerBase = {
-  prepare(
-    entity: Entity,
-    options?: {
-      logger?: Logger_2;
-      etag?: string;
-    },
-  ): Promise<PreparerResponse>;
+  prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 };

-// Warning: (ae-missing-release-tag) "PreparerBuilder" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type PreparerBuilder = {
  register(protocol: RemoteProtocol, preparer: PreparerBase): void;
  get(entity: Entity): PreparerBase;
 };

-// Warning: (ae-missing-release-tag) "Preparers" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type PreparerConfig = {
+  logger: Logger_2;
+  reader: UrlReader;
+};
+
+// @public
+export type PreparerOptions = {
+  logger?: Logger_2;
+  etag?: ETag;
+};
+
+// @public
+export type PreparerResponse = {
+  preparedDir: string;
+  etag: ETag;
+};
+
+// @public
 export class Preparers implements PreparerBuilder {
-  // Warning: (ae-forgotten-export) The symbol "factoryOptions" needs to be exported by the entry point index.d.ts
-  //
-  // (undocumented)
  static fromConfig(
-    config: Config,
-    { logger, reader }: factoryOptions,
+    backstageConfig: Config,
+    { logger, reader }: PreparerConfig,
  ): Promise<PreparerBuilder>;
-  // (undocumented)
  get(entity: Entity): PreparerBase;
-  // (undocumented)
  register(protocol: RemoteProtocol, preparer: PreparerBase): void;
 }

-// Warning: (ae-missing-release-tag) "Publisher" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export class Publisher {
-  // Warning: (ae-forgotten-export) The symbol "factoryOptions" needs to be exported by the entry point index.d.ts
-  //
-  // (undocumented)
  static fromConfig(
    config: Config,
-    { logger, discovery }: factoryOptions_2,
+    { logger, discovery }: PublisherFactory,
  ): Promise<PublisherBase>;
 }

@@ -172,15 +160,16 @@ export interface PublisherBase {
  fetchTechDocsMetadata(entityName: EntityName): Promise<TechDocsMetadata>;
  getReadiness(): Promise<ReadinessResponse>;
  hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
-  // Warning: (ae-forgotten-export) The symbol "MigrateRequest" needs to be exported by the entry point index.d.ts
  migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;
-  // Warning: (ae-forgotten-export) The symbol "PublishRequest" needs to be exported by the entry point index.d.ts
-  // Warning: (ae-forgotten-export) The symbol "PublishResponse" needs to be exported by the entry point index.d.ts
  publish(request: PublishRequest): Promise<PublishResponse>;
 }

-// Warning: (ae-missing-release-tag) "PublisherType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
+// @public
+export type PublisherFactory = {
+  logger: Logger_2;
+  discovery: PluginEndpointDiscovery;
+};
+
 // @public
 export type PublisherType =
  | 'local'
@@ -189,37 +178,40 @@ export type PublisherType =
  | 'azureBlobStorage'
  | 'openStackSwift';

+// @public
+export type PublishRequest = {
+  entity: Entity;
+  directory: string;
+};
+
+// @public
+export type PublishResponse = {
+  remoteUrl?: string;
+  objects?: string[];
+} | void;
+
 // @public
 export type ReadinessResponse = {
  isAvailable: boolean;
 };

-// Warning: (ae-missing-release-tag) "RemoteProtocol" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export type RemoteProtocol = 'url' | 'dir';

-// Warning: (ae-missing-release-tag) "TechDocsDocument" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
+export type SupportedGeneratorKey = 'techdocs' | string;
+
+// @public
 export interface TechDocsDocument extends IndexableDocument {
-  // (undocumented)
  kind: string;
-  // (undocumented)
  lifecycle: string;
-  // (undocumented)
  name: string;
-  // (undocumented)
  namespace: string;
-  // (undocumented)
  owner: string;
-  // (undocumented)
  path: string;
 }

-// Warning: (ae-missing-release-tag) "TechdocsGenerator" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class TechdocsGenerator implements GeneratorBase {
  constructor(options: {
    logger: Logger_2;
@@ -228,20 +220,13 @@ export class TechdocsGenerator implements GeneratorBase {
    scmIntegrations: ScmIntegrationRegistry;
  });
  static readonly defaultDockerImage = 'spotify/techdocs:v0.3.7';
-  // (undocumented)
  static fromConfig(
    config: Config,
-    options: {
-      containerRunner: ContainerRunner;
-      logger: Logger_2;
-    },
+    options: GeneratorOptions,
  ): TechdocsGenerator;
-  // (undocumented)
  run(options: GeneratorRunOptions): Promise<void>;
 }

-// Warning: (ae-missing-release-tag) "TechDocsMetadata" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export type TechDocsMetadata = {
  site_name: string;
@@ -251,8 +236,6 @@ export type TechDocsMetadata = {
  files?: string[];
 };

-// Warning: (ae-missing-release-tag) "transformDirLocation" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 export const transformDirLocation: (
  entity: Entity,
@@ -263,21 +246,11 @@ export const transformDirLocation: (
  target: string;
 };

-// Warning: (ae-missing-release-tag) "UrlPreparer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 export class UrlPreparer implements PreparerBase {
+  // @deprecated
  constructor(reader: UrlReader, logger: Logger_2);
-  // (undocumented)
-  prepare(
-    entity: Entity,
-    options?: {
-      etag?: string;
-    },
-  ): Promise<PreparerResponse>;
+  static fromConfig({ reader, logger }: PreparerConfig): UrlPreparer;
+  prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 }
-
-// Warnings were encountered during analysis:
-//
-// src/stages/generate/types.d.ts:45:5 - (ae-forgotten-export) The symbol "SupportedGeneratorKey" needs to be exported by the entry point index.d.ts
 ```
@@ -26,11 +26,21 @@ import path from 'path';
 import { Logger } from 'winston';
 import { PreparerResponse, RemoteProtocol } from './stages/prepare/types';

+/**
+ * Parsed location annotation
+ * @public
+ */
 export type ParsedLocationAnnotation = {
  type: RemoteProtocol;
  target: string;
 };

+/**
+ * Returns a parset locations annotation
+ * @public
+ * @param annotationName - The name of the annotation in the entity metadata
+ * @param entity - A TechDocs entity instance
+ */
 export const parseReferenceAnnotation = (
  annotationName: string,
  entity: Entity,
@@ -56,7 +66,7 @@ export const parseReferenceAnnotation = (
 * location, it returns a `url` location with a resolved target that points to the
 * targeted subfolder. If the entity was registered by a `file` location, it returns
 * an absolute `dir` location.
- *
+ * @public
 * @param entity - the entity with annotations
 * @param dirAnnotation - the parsed techdocs-ref annotation of type 'dir'
 * @param scmIntegrations - access to the scmIntegration to do url transformations
@@ -101,6 +111,12 @@ export const transformDirLocation = (
  }
 };

+/**
+ * Returns a entity reference based on the TechDocs annotation type
+ * @public
+ * @param entity - A TechDocs instance
+ * @param scmIntegration - An implementation for  SCM integration API
+ */
 export const getLocationForEntity = (
  entity: Entity,
  scmIntegration: ScmIntegrationRegistry,
@@ -120,6 +136,13 @@ export const getLocationForEntity = (
  }
 };

+/**
+ * Returns a preparer response {@link PreparerResponse}
+ * @public
+ * @param reader - Read a tree of files from a repository
+ * @param entity - A TechDocs entity instance
+ * @param opts - Options for configuring the reader, e.g. logger, etag, etc.
+ */
 export const getDocFilesFromRepository = async (
  reader: UrlReader,
  entity: Entity,
@@ -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 TechDocs
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the TechDocs 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 TechDocs entity
+   * @param entity - A TechDocs entity instance
+   */
  get(entity: Entity): GeneratorBase {
    const generatorKey = getGeneratorKey(entity);
    const generator = this.generatorMap.get(generatorKey);
@@ -16,7 +16,9 @@
 export { TechdocsGenerator } from './techdocs';
 export { Generators } from './generators';
 export type {
-  GeneratorBuilder,
  GeneratorBase,
+  GeneratorOptions,
+  GeneratorBuilder,
  GeneratorRunOptions,
+  SupportedGeneratorKey,
 } from './types';
@@ -34,11 +34,16 @@ import {
 import {
  GeneratorBase,
  GeneratorConfig,
+  GeneratorOptions,
  GeneratorRunInType,
  GeneratorRunOptions,
 } from './types';
 import { ForwardedError } from '@backstage/errors';

+/**
+ * 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 TechDocs generator
+   * @param config - A Backstage configuration
+   * @param options - Options to configure the generator
+   */
+  static fromConfig(config: Config, options: GeneratorOptions) {
    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,
@@ -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 GeneratorOptions = {
+  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;
@@ -24,20 +24,43 @@ import {
 } from '@backstage/integration';
 import { Logger } from 'winston';
 import { parseReferenceAnnotation, transformDirLocation } from '../../helpers';
-import { PreparerBase, PreparerResponse } from './types';
+import {
+  PreparerBase,
+  PreparerConfig,
+  PreparerOptions,
+  PreparerResponse,
+} from './types';

+/**
+ * Preparer used to retrieve documentation files from a local directory
+ * @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);
  }

+  /**
+   * Returns a directory preparer instance
+   * @param config - A backstage config
+   * @param options - A directory preparer options containing a logger and reader
+   */
+  static fromConfig(
+    config: Config,
+    { logger, reader }: PreparerConfig,
+  ): DirectoryPreparer {
+    return new DirectoryPreparer(config, logger, reader);
+  }
+
+  /** {@inheritDoc PreparerBase.prepare} */
  async prepare(
    entity: Entity,
-    options?: { logger?: Logger; etag?: string },
+    options?: PreparerOptions,
  ): Promise<PreparerResponse> {
    const annotation = parseReferenceAnnotation(
      'backstage.io/techdocs-ref',
@@ -16,4 +16,12 @@
 export { DirectoryPreparer } from './dir';
 export { UrlPreparer } from './url';
 export { Preparers } from './preparers';
-export type { PreparerBuilder, PreparerBase, RemoteProtocol } from './types';
+export type {
+  PreparerBase,
+  PreparerBuilder,
+  PreparerConfig,
+  PreparerOptions,
+  PreparerResponse,
+  RemoteProtocol,
+  ETag,
+} from './types';
@@ -13,26 +13,34 @@
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
-import { UrlReader } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-import { Logger } from 'winston';
 import { parseReferenceAnnotation } from '../../helpers';
 import { DirectoryPreparer } from './dir';
 import { UrlPreparer } from './url';
-import { PreparerBase, PreparerBuilder, RemoteProtocol } from './types';
-
-type factoryOptions = {
-  logger: Logger;
-  reader: UrlReader;
-};
+import {
+  PreparerBase,
+  PreparerBuilder,
+  PreparerConfig,
+  RemoteProtocol,
+} from './types';

+/**
+ * Collection of docs preparers (dir and url)
+ * @public
+ */
 export class Preparers implements PreparerBuilder {
  private preparerMap = new Map<RemoteProtocol, PreparerBase>();

+  /**
+   * Returns a generators instance containing a generator for TechDocs
+   * @public
+   * @param backstageConfig - A Backstage configuration
+   * @param preparerConfig - Options to configure preparers
+   */
  static async fromConfig(
-    config: Config,
-    { logger, reader }: factoryOptions,
+    backstageConfig: Config,
+    { logger, reader }: PreparerConfig,
  ): Promise<PreparerBuilder> {
    const preparers = new Preparers();

@@ -43,16 +51,30 @@ export class Preparers implements PreparerBuilder {
     * Dir preparer is a syntactic sugar for users to define techdocs-ref annotation.
     * When using dir preparer, the docs will be fetched using URL Reader.
     */
-    const directoryPreparer = new DirectoryPreparer(config, logger, reader);
+    const directoryPreparer = new DirectoryPreparer(
+      backstageConfig,
+      logger,
+      reader,
+    );
    preparers.register('dir', directoryPreparer);

    return preparers;
  }

+  /**
+   * Register a preparer in the preparers collection
+   * @param protocol - url or dir to associate with preparer
+   * @param preparer - The preparer instance to set
+   */
  register(protocol: RemoteProtocol, preparer: PreparerBase) {
    this.preparerMap.set(protocol, preparer);
  }

+  /**
+   * Returns the preparer for a given TechDocs entity
+   * @param entity - A TechDocs entity instance
+   * @returns
+   */
  get(entity: Entity): PreparerBase {
    const { type } = parseReferenceAnnotation(
      'backstage.io/techdocs-ref',
@@ -15,19 +15,58 @@
 */

 import type { Entity } from '@backstage/catalog-model';
+import { UrlReader } from '@backstage/backend-common';
 import { Logger } from 'winston';

+/**
+ * A unique identifier of the tree blob, usually the commit SHA or etag from the target.
+ * @public
+ */
+export type ETag = string;
+
+/**
+ * Options for building preparers
+ * @public
+ */
+export type PreparerConfig = {
+  logger: Logger;
+  reader: UrlReader;
+};
+
+/**
+ * Options for configuring the content preparation process.
+ * @public
+ */
+export type PreparerOptions = {
+  /**
+   * An instance of the logger
+   */
+  logger?: Logger;
+  /**
+   * see {@link ETag}
+   */
+  etag?: ETag;
+};
+
+/**
+ * Result of the preparation step.
+ * @public
+ */
 export type PreparerResponse = {
  /**
   * The path to directory where the tree is downloaded.
   */
  preparedDir: string;
  /**
-   * A unique identifier of the tree blob, usually the commit SHA or etag from the target.
+   * see {@link ETag}
   */
-  etag: string;
+  etag: ETag;
 };

+/**
+ * Definition of a TechDocs preparer
+ * @public
+ */
 export type PreparerBase = {
  /**
   * Given an Entity definition from the Software Catalog, go and prepare a directory
@@ -38,15 +77,20 @@ export type PreparerBase = {
   *        updated since the last build.
   * @throws `NotModifiedError` when the prepared directory has not been changed since the last build.
   */
-  prepare(
-    entity: Entity,
-    options?: { logger?: Logger; etag?: string },
-  ): Promise<PreparerResponse>;
+  prepare(entity: Entity, options?: PreparerOptions): Promise<PreparerResponse>;
 };

+/**
+ * Definition for a TechDocs preparer builder
+ * @public
+ */
 export type PreparerBuilder = {
  register(protocol: RemoteProtocol, preparer: PreparerBase): void;
  get(entity: Entity): PreparerBase;
 };

+/**
+ * Location where documentation files are stored
+ * @public
+ */
 export type RemoteProtocol = 'url' | 'dir';
@@ -19,20 +19,39 @@ import { UrlReader } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import { Logger } from 'winston';
 import { getDocFilesFromRepository } from '../../helpers';
-import { PreparerBase, PreparerResponse } from './types';
+import {
+  PreparerBase,
+  PreparerConfig,
+  PreparerOptions,
+  PreparerResponse,
+} from './types';

+/**
+ * Preparer used to retrieve documentation files from a remote repository
+ * @public
+ */
 export class UrlPreparer implements PreparerBase {
  private readonly logger: Logger;
  private readonly reader: UrlReader;

+  /**  @deprecated use static fromConfig method instead */
  constructor(reader: UrlReader, logger: Logger) {
    this.logger = logger;
    this.reader = reader;
  }

+  /**
+   * Returns a directory preparer instance
+   * @param config - A URL preparer config containing the a logger and reader
+   */
+  static fromConfig({ reader, logger }: PreparerConfig): UrlPreparer {
+    return new UrlPreparer(reader, logger);
+  }
+
+  /** {@inheritDoc PreparerBase.prepare} */
  async prepare(
    entity: Entity,
-    options?: { etag?: string },
+    options?: PreparerOptions,
  ): Promise<PreparerResponse> {
    try {
      return await getDocFilesFromRepository(this.reader, entity, {
@@ -17,6 +17,10 @@ export { Publisher } from './publish';
 export type {
  PublisherBase,
  PublisherType,
-  TechDocsMetadata,
+  PublisherFactory,
+  PublishRequest,
+  PublishResponse,
+  MigrateRequest,
  ReadinessResponse,
+  TechDocsMetadata,
 } from './types';
@@ -14,29 +14,28 @@
 * limitations under the License.
 */

-import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { Config } from '@backstage/config';
-import { Logger } from 'winston';
 import { AwsS3Publish } from './awsS3';
 import { AzureBlobStoragePublish } from './azureBlobStorage';
 import { GoogleGCSPublish } from './googleStorage';
 import { LocalPublish } from './local';
 import { OpenStackSwiftPublish } from './openStackSwift';
-import { PublisherBase, PublisherType } from './types';
-
-type factoryOptions = {
-  logger: Logger;
-  discovery: PluginEndpointDiscovery;
-};
+import { PublisherFactory, PublisherBase, PublisherType } from './types';

 /**
 * Factory class to create a TechDocs publisher based on defined publisher type in app config.
 * Uses `techdocs.publisher.type`.
+ * @public
 */
 export class Publisher {
+  /**
+   * Returns a instance of TechDocs publisher
+   * @param config - A Backstage configuration
+   * @param options - Options for configuring the publisher factory
+   */
  static async fromConfig(
    config: Config,
-    { logger, discovery }: factoryOptions,
+    { logger, discovery }: PublisherFactory,
  ): Promise<PublisherBase> {
    const publisherType = (config.getOptionalString(
      'techdocs.publisher.type',
@@ -14,10 +14,22 @@
 * limitations under the License.
 */
 import { Entity, EntityName } from '@backstage/catalog-model';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { Logger } from 'winston';
 import express from 'express';

+/**
+ * Options for building publishers
+ * @public
+ */
+export type PublisherFactory = {
+  logger: Logger;
+  discovery: PluginEndpointDiscovery;
+};
+
 /**
 * Key for all the different types of TechDocs publishers that are supported.
+ * @public
 */
 export type PublisherType =
  | 'local'
@@ -26,6 +38,10 @@ export type PublisherType =
  | 'azureBlobStorage'
  | 'openStackSwift';

+/**
+ * Request publish definition
+ * @public
+ */
 export type PublishRequest = {
  entity: Entity;
  /* The Path to the directory where the generated files are stored. */
@@ -35,6 +51,7 @@ export type PublishRequest = {
 /**
 * Response containing metadata about where files were published and what may
 * have been published or updated.
+ * @public
 */
 export type PublishResponse = {
  /**
@@ -51,7 +68,6 @@ export type PublishResponse = {

 /**
 * Result for the validation check.
- *
 * @public
 */
 export type ReadinessResponse = {
@@ -62,6 +78,7 @@ export type ReadinessResponse = {
 /**
 * Type to hold metadata found in techdocs_metadata.json and associated with each site
 * @param etag - ETag of the resource used to generate the site. Usually the latest commit sha of the source repository.
+ * @public
 */
 export type TechDocsMetadata = {
  site_name: string;
@@ -71,6 +88,10 @@ export type TechDocsMetadata = {
  files?: string[];
 };

+/**
+ * TechDocs entity triplet migration request
+ * @public
+ */
 export type MigrateRequest = {
  /**
   * Whether or not to remove the source file. Defaults to false (acting like a
@@ -16,11 +16,33 @@

 import { IndexableDocument } from '@backstage/search-common';

+/**
+ * TechDocs indexable document interface
+ * @public
+ */
 export interface TechDocsDocument extends IndexableDocument {
+  /**
+   * Entity kind
+   */
  kind: string;
+  /**
+   * Entity metadata namespace
+   */
  namespace: string;
+  /**
+   * Entity metadata name
+   */
  name: string;
+  /**
+   * Entity lifecycle
+   */
  lifecycle: string;
+  /**
+   * Entity owner
+   */
  owner: string;
+  /**
+   * Entity path
+   */
  path: string;
 }