diff --git a/.changeset/big-garlics-punch.md b/.changeset/big-garlics-punch.md new file mode 100644 index 0000000000..7f184aa38c --- /dev/null +++ b/.changeset/big-garlics-punch.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs-node': patch +--- + +Move `TechdocsContainerRunner` from `publish` to `generate`. diff --git a/plugins/techdocs-node/src/stages/generate/DockerContainerRunner.ts b/plugins/techdocs-node/src/stages/generate/DockerContainerRunner.ts index b7cb7f1c86..9288822435 100644 --- a/plugins/techdocs-node/src/stages/generate/DockerContainerRunner.ts +++ b/plugins/techdocs-node/src/stages/generate/DockerContainerRunner.ts @@ -20,6 +20,7 @@ import { ForwardedError } from '@backstage/errors'; import { PassThrough } from 'stream'; import { pipeline as pipelineStream } from 'stream'; import { promisify } from 'util'; +import { TechDocsContainerRunner } from './types'; import { Writable } from 'stream'; const pipeline = promisify(pipelineStream); @@ -31,7 +32,7 @@ export type UserOptions = { /** * @internal */ -export class DockerContainerRunner { +export class DockerContainerRunner implements TechDocsContainerRunner { private readonly dockerClient: Docker; constructor() { diff --git a/plugins/techdocs-node/src/stages/generate/generators.ts b/plugins/techdocs-node/src/stages/generate/generators.ts index 7c8d169d1e..d7b7a71eb3 100644 --- a/plugins/techdocs-node/src/stages/generate/generators.ts +++ b/plugins/techdocs-node/src/stages/generate/generators.ts @@ -24,7 +24,7 @@ import { SupportedGeneratorKey, } from './types'; import { LoggerService } from '@backstage/backend-plugin-api'; -import { TechDocsContainerRunner } from '../publish/types'; +import { TechDocsContainerRunner } from './types'; /** * Collection of docs generators diff --git a/plugins/techdocs-node/src/stages/generate/index.ts b/plugins/techdocs-node/src/stages/generate/index.ts index aaf27026c2..10e1e72ed3 100644 --- a/plugins/techdocs-node/src/stages/generate/index.ts +++ b/plugins/techdocs-node/src/stages/generate/index.ts @@ -22,6 +22,7 @@ export type { GeneratorBuilder, GeneratorRunOptions, SupportedGeneratorKey, + TechDocsContainerRunner, } from './types'; import { getMkdocsYml } from './helpers'; /** diff --git a/plugins/techdocs-node/src/stages/generate/techdocs.ts b/plugins/techdocs-node/src/stages/generate/techdocs.ts index 554f1c29bd..7329878142 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.ts +++ b/plugins/techdocs-node/src/stages/generate/techdocs.ts @@ -43,7 +43,7 @@ import { import { ForwardedError } from '@backstage/errors'; import { DockerContainerRunner } from './DockerContainerRunner'; import { LoggerService } from '@backstage/backend-plugin-api'; -import { TechDocsContainerRunner } from '../publish/types'; +import { TechDocsContainerRunner } from './types'; /** * Generates documentation files diff --git a/plugins/techdocs-node/src/stages/generate/types.ts b/plugins/techdocs-node/src/stages/generate/types.ts index c7513d2710..fd4cb62820 100644 --- a/plugins/techdocs-node/src/stages/generate/types.ts +++ b/plugins/techdocs-node/src/stages/generate/types.ts @@ -19,9 +19,11 @@ import { Writable } from 'stream'; import { Logger } from 'winston'; import { ParsedLocationAnnotation } from '../../helpers'; import { LoggerService } from '@backstage/backend-plugin-api'; -import { TechDocsContainerRunner } from '../publish/types'; -// Determines where the generator will be run +/** + * Determines where the generator will be run. `'docker'` is a shorthand for running the generator in a container. + * If no {@link GeneratorOptions.containerRunner} is specified, the internal `DockerContainerRunner` will be used. + */ export type GeneratorRunInType = 'docker' | 'local'; /** @@ -30,10 +32,6 @@ export type GeneratorRunInType = 'docker' | 'local'; */ export type GeneratorOptions = { logger: LoggerService; - /** - * @deprecated containerRunner is now instantiated in - * the generator and this option will be removed in the future - */ containerRunner?: TechDocsContainerRunner; }; @@ -104,3 +102,39 @@ export type DefaultMkdocsContent = { docs_dir: string; plugins: String[]; }; + +/** + * Handles the running of containers to generate TechDocs. + * + * Custom implementations, e.g. for Kubernetes or other execution environments, can be inspired by the internal default + * implementation `DockerContainerRunner`. + * + * @public + */ +export interface TechDocsContainerRunner { + /** + * Runs a container image to completion. + */ + runContainer(opts: { + imageName: string; + command?: string | string[]; + args: string[]; + logStream?: Writable; + mountDirs?: Record; + workingDir?: string; + envVars?: Record; + pullImage?: boolean; + defaultUser?: boolean; + pullOptions?: { + authconfig?: { + username?: string; + password?: string; + auth?: string; + email?: string; + serveraddress?: string; + [key: string]: unknown; + }; + [key: string]: unknown; + }; + }): Promise; +} diff --git a/plugins/techdocs-node/src/stages/publish/index.ts b/plugins/techdocs-node/src/stages/publish/index.ts index 8b6465c719..7f6859367f 100644 --- a/plugins/techdocs-node/src/stages/publish/index.ts +++ b/plugins/techdocs-node/src/stages/publish/index.ts @@ -24,5 +24,4 @@ export type { MigrateRequest, ReadinessResponse, TechDocsMetadata, - TechDocsContainerRunner, } from './types'; diff --git a/plugins/techdocs-node/src/stages/publish/types.ts b/plugins/techdocs-node/src/stages/publish/types.ts index 89af730404..720f1b218a 100644 --- a/plugins/techdocs-node/src/stages/publish/types.ts +++ b/plugins/techdocs-node/src/stages/publish/types.ts @@ -13,7 +13,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { Writable } from 'stream'; import express from 'express'; import { Config } from '@backstage/config'; import { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api'; @@ -168,36 +167,3 @@ export type PublisherBuilder = { register(type: PublisherType, publisher: PublisherBase): void; get(config: Config): PublisherBase; }; - -/** - * Handles the running of containers, on behalf of others. - * - * @public - */ -export interface TechDocsContainerRunner { - /** - * Runs a container image to completion. - */ - runContainer(opts: { - imageName: string; - command?: string | string[]; - args: string[]; - logStream?: Writable; - mountDirs?: Record; - workingDir?: string; - envVars?: Record; - pullImage?: boolean; - defaultUser?: boolean; - pullOptions?: { - authconfig?: { - username?: string; - password?: string; - auth?: string; - email?: string; - serveraddress?: string; - [key: string]: unknown; - }; - [key: string]: unknown; - }; - }): Promise; -}