diff --git a/.changeset/techdocs-hornets-turn.md b/.changeset/techdocs-hornets-turn.md new file mode 100644 index 0000000000..d838ca5ba2 --- /dev/null +++ b/.changeset/techdocs-hornets-turn.md @@ -0,0 +1,5 @@ +--- +'@backstage/techdocs-common': patch +--- + +Clean up the API interface for TechDocs common library. diff --git a/packages/techdocs-common/api-report.md b/packages/techdocs-common/api-report.md index f189a85c0c..7c4fc95abb 100644 --- a/packages/techdocs-common/api-report.md +++ b/packages/techdocs-common/api-report.md @@ -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; + // @deprecated + constructor(config: Config, _logger: Logger_2 | null, reader: UrlReader); + static fromConfig( + config: Config, + { logger, reader }: PreparerConfig, + ): DirectoryPreparer; + prepare(entity: Entity, options?: PreparerOptions): Promise; } -// 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; }; -// 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; - // (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; -// 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; + prepare(entity: Entity, options?: PreparerOptions): Promise; }; -// 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; - // (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; } @@ -172,15 +160,16 @@ export interface PublisherBase { fetchTechDocsMetadata(entityName: EntityName): Promise; getReadiness(): Promise; hasDocsBeenGenerated(entityName: Entity): Promise; - // Warning: (ae-forgotten-export) The symbol "MigrateRequest" needs to be exported by the entry point index.d.ts migrateDocsCase?(migrateRequest: MigrateRequest): Promise; - // 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; } -// 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; } -// 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; + static fromConfig({ reader, logger }: PreparerConfig): UrlPreparer; + prepare(entity: Entity, options?: PreparerOptions): Promise; } - -// 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 ``` diff --git a/packages/techdocs-common/src/helpers.ts b/packages/techdocs-common/src/helpers.ts index ccf1256381..39a1f4c666 100644 --- a/packages/techdocs-common/src/helpers.ts +++ b/packages/techdocs-common/src/helpers.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, diff --git a/packages/techdocs-common/src/stages/generate/generators.ts b/packages/techdocs-common/src/stages/generate/generators.ts index de39d4e7c3..630fccfa44 100644 --- a/packages/techdocs-common/src/stages/generate/generators.ts +++ b/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(); + /** + * 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); diff --git a/packages/techdocs-common/src/stages/generate/index.ts b/packages/techdocs-common/src/stages/generate/index.ts index eb015a5c2d..1c20c58887 100644 --- a/packages/techdocs-common/src/stages/generate/index.ts +++ b/packages/techdocs-common/src/stages/generate/index.ts @@ -16,7 +16,9 @@ export { TechdocsGenerator } from './techdocs'; export { Generators } from './generators'; export type { - GeneratorBuilder, GeneratorBase, + GeneratorOptions, + GeneratorBuilder, GeneratorRunOptions, + SupportedGeneratorKey, } from './types'; diff --git a/packages/techdocs-common/src/stages/generate/techdocs.ts b/packages/techdocs-common/src/stages/generate/techdocs.ts index 99554a6218..baa2e008a1 100644 --- a/packages/techdocs-common/src/stages/generate/techdocs.ts +++ b/packages/techdocs-common/src/stages/generate/techdocs.ts @@ -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 { const { inputDir, diff --git a/packages/techdocs-common/src/stages/generate/types.ts b/packages/techdocs-common/src/stages/generate/types.ts index 2a090d5584..2ff3064991 100644 --- a/packages/techdocs-common/src/stages/generate/types.ts +++ b/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 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; }; /** * 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; diff --git a/packages/techdocs-common/src/stages/prepare/dir.ts b/packages/techdocs-common/src/stages/prepare/dir.ts index ade0b00162..42bfa5b903 100644 --- a/packages/techdocs-common/src/stages/prepare/dir.ts +++ b/packages/techdocs-common/src/stages/prepare/dir.ts @@ -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 { const annotation = parseReferenceAnnotation( 'backstage.io/techdocs-ref', diff --git a/packages/techdocs-common/src/stages/prepare/index.ts b/packages/techdocs-common/src/stages/prepare/index.ts index f129bf5315..3593b49c86 100644 --- a/packages/techdocs-common/src/stages/prepare/index.ts +++ b/packages/techdocs-common/src/stages/prepare/index.ts @@ -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'; diff --git a/packages/techdocs-common/src/stages/prepare/preparers.ts b/packages/techdocs-common/src/stages/prepare/preparers.ts index 75c9a7f23b..575294e91a 100644 --- a/packages/techdocs-common/src/stages/prepare/preparers.ts +++ b/packages/techdocs-common/src/stages/prepare/preparers.ts @@ -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(); + /** + * 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 { 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', diff --git a/packages/techdocs-common/src/stages/prepare/types.ts b/packages/techdocs-common/src/stages/prepare/types.ts index 5c219752fa..aee9d216ab 100644 --- a/packages/techdocs-common/src/stages/prepare/types.ts +++ b/packages/techdocs-common/src/stages/prepare/types.ts @@ -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; + prepare(entity: Entity, options?: PreparerOptions): Promise; }; +/** + * 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'; diff --git a/packages/techdocs-common/src/stages/prepare/url.ts b/packages/techdocs-common/src/stages/prepare/url.ts index cd4a8860e4..8026dca41e 100644 --- a/packages/techdocs-common/src/stages/prepare/url.ts +++ b/packages/techdocs-common/src/stages/prepare/url.ts @@ -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 { try { return await getDocFilesFromRepository(this.reader, entity, { diff --git a/packages/techdocs-common/src/stages/publish/index.ts b/packages/techdocs-common/src/stages/publish/index.ts index 083cf2b8ff..c6f86f6bc1 100644 --- a/packages/techdocs-common/src/stages/publish/index.ts +++ b/packages/techdocs-common/src/stages/publish/index.ts @@ -17,6 +17,10 @@ export { Publisher } from './publish'; export type { PublisherBase, PublisherType, - TechDocsMetadata, + PublisherFactory, + PublishRequest, + PublishResponse, + MigrateRequest, ReadinessResponse, + TechDocsMetadata, } from './types'; diff --git a/packages/techdocs-common/src/stages/publish/publish.ts b/packages/techdocs-common/src/stages/publish/publish.ts index eb9e3104bf..bc7f50b5a3 100644 --- a/packages/techdocs-common/src/stages/publish/publish.ts +++ b/packages/techdocs-common/src/stages/publish/publish.ts @@ -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 { const publisherType = (config.getOptionalString( 'techdocs.publisher.type', diff --git a/packages/techdocs-common/src/stages/publish/types.ts b/packages/techdocs-common/src/stages/publish/types.ts index 37075a35a4..c6ad032484 100644 --- a/packages/techdocs-common/src/stages/publish/types.ts +++ b/packages/techdocs-common/src/stages/publish/types.ts @@ -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 diff --git a/packages/techdocs-common/src/techdocsTypes.ts b/packages/techdocs-common/src/techdocsTypes.ts index 4aa3972b31..0b722f4da5 100644 --- a/packages/techdocs-common/src/techdocsTypes.ts +++ b/packages/techdocs-common/src/techdocsTypes.ts @@ -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; }