From 67cff7b06feda44d8d67ac98f5bd52ad43597678 Mon Sep 17 00:00:00 2001 From: Phil Kuang Date: Thu, 12 Oct 2023 18:56:45 -0400 Subject: [PATCH 1/3] feat(techdocs): add extension for setting build strategy Signed-off-by: Phil Kuang --- .changeset/two-jars-melt.md | 6 ++++ plugins/techdocs-backend/api-report.md | 14 +++----- plugins/techdocs-backend/src/index.ts | 8 +++-- plugins/techdocs-backend/src/plugin.ts | 13 +++++++ ...st.ts => DefaultDocsBuildStrategy.test.ts} | 2 +- ...trategy.ts => DefaultDocsBuildStrategy.ts} | 25 +++---------- plugins/techdocs-backend/src/service/index.ts | 4 --- .../src/service/router.test.ts | 2 +- .../techdocs-backend/src/service/router.ts | 6 ++-- plugins/techdocs-node/api-report.md | 21 +++++++++++ plugins/techdocs-node/package.json | 1 + plugins/techdocs-node/src/extensions.ts | 36 +++++++++++++++++++ plugins/techdocs-node/src/index.ts | 4 +++ plugins/techdocs-node/src/techdocsTypes.ts | 19 ++++++++++ yarn.lock | 1 + 15 files changed, 119 insertions(+), 43 deletions(-) create mode 100644 .changeset/two-jars-melt.md rename plugins/techdocs-backend/src/service/{DocsBuildStrategy.test.ts => DefaultDocsBuildStrategy.test.ts} (96%) rename plugins/techdocs-backend/src/service/{DocsBuildStrategy.ts => DefaultDocsBuildStrategy.ts} (66%) create mode 100644 plugins/techdocs-node/src/extensions.ts diff --git a/.changeset/two-jars-melt.md b/.changeset/two-jars-melt.md new file mode 100644 index 0000000000..d6f0166885 --- /dev/null +++ b/.changeset/two-jars-melt.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs-backend': minor +'@backstage/plugin-techdocs-node': minor +--- + +Expose an extension point to set a custom build strategy and move `DocsBuildStrategy` and `ShouldBuildParameters` types to `@backstage/plugin-techdocs-node` diff --git a/plugins/techdocs-backend/api-report.md b/plugins/techdocs-backend/api-report.md index b8974e6d4f..6e2fbc4c53 100644 --- a/plugins/techdocs-backend/api-report.md +++ b/plugins/techdocs-backend/api-report.md @@ -7,7 +7,7 @@ import { CatalogApi } from '@backstage/catalog-client'; import { CatalogClient } from '@backstage/catalog-client'; import { Config } from '@backstage/config'; import { DefaultTechDocsCollatorFactory as DefaultTechDocsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-techdocs'; -import { Entity } from '@backstage/catalog-model'; +import { DocsBuildStrategy } from '@backstage/plugin-techdocs-node'; import express from 'express'; import { GeneratorBuilder } from '@backstage/plugin-techdocs-node'; import { Knex } from 'knex'; @@ -17,6 +17,7 @@ import { PluginCacheManager } from '@backstage/backend-common'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; import { PreparerBuilder } from '@backstage/plugin-techdocs-node'; import { PublisherBase } from '@backstage/plugin-techdocs-node'; +import { ShouldBuildParameters } from '@backstage/plugin-techdocs-node'; import type { TechDocsCollatorFactoryOptions as TechDocsCollatorFactoryOptions_2 } from '@backstage/plugin-search-backend-module-techdocs'; import { TechDocsDocument } from '@backstage/plugin-techdocs-node'; import { TokenManager } from '@backstage/backend-common'; @@ -48,11 +49,7 @@ export class DefaultTechDocsCollator { // @public @deprecated (undocumented) export const DefaultTechDocsCollatorFactory: typeof DefaultTechDocsCollatorFactory_2; -// @public -export interface DocsBuildStrategy { - // (undocumented) - shouldBuild(params: ShouldBuildParameters): Promise; -} +export { DocsBuildStrategy }; // @public export type OutOfTheBoxDeploymentOptions = { @@ -86,10 +83,7 @@ export type RouterOptions = | RecommendedDeploymentOptions | OutOfTheBoxDeploymentOptions; -// @public -export type ShouldBuildParameters = { - entity: Entity; -}; +export { ShouldBuildParameters }; // @public @deprecated (undocumented) export type TechDocsCollatorFactoryOptions = TechDocsCollatorFactoryOptions_2; diff --git a/plugins/techdocs-backend/src/index.ts b/plugins/techdocs-backend/src/index.ts index dc5d87d1b3..cf70db39e8 100644 --- a/plugins/techdocs-backend/src/index.ts +++ b/plugins/techdocs-backend/src/index.ts @@ -25,8 +25,6 @@ export type { RouterOptions, RecommendedDeploymentOptions, OutOfTheBoxDeploymentOptions, - DocsBuildStrategy, - ShouldBuildParameters, } from './service'; export { @@ -41,6 +39,10 @@ export type { /** * @deprecated Use directly from @backstage/plugin-techdocs-node */ -export type { TechDocsDocument } from '@backstage/plugin-techdocs-node'; +export type { + DocsBuildStrategy, + ShouldBuildParameters, + TechDocsDocument, +} from '@backstage/plugin-techdocs-node'; export * from '@backstage/plugin-techdocs-node'; diff --git a/plugins/techdocs-backend/src/plugin.ts b/plugins/techdocs-backend/src/plugin.ts index 745370b67a..2dcde1a975 100644 --- a/plugins/techdocs-backend/src/plugin.ts +++ b/plugins/techdocs-backend/src/plugin.ts @@ -25,9 +25,11 @@ import { } from '@backstage/backend-plugin-api'; import { + DocsBuildStrategy, Preparers, Generators, Publisher, + techdocsBuildStrategyExtensionPoint, } from '@backstage/plugin-techdocs-node'; import Docker from 'dockerode'; import { createRouter } from '@backstage/plugin-techdocs-backend'; @@ -39,6 +41,16 @@ import { createRouter } from '@backstage/plugin-techdocs-backend'; export const techdocsPlugin = createBackendPlugin({ pluginId: 'techdocs', register(env) { + let docsBuildStrategy: DocsBuildStrategy | undefined; + env.registerExtensionPoint(techdocsBuildStrategyExtensionPoint, { + setBuildStrategy(buildStrategy: DocsBuildStrategy) { + if (docsBuildStrategy) { + throw new Error('DocsBuildStrategy may only be set once'); + } + docsBuildStrategy = buildStrategy; + }, + }); + env.registerInit({ deps: { config: coreServices.rootConfig, @@ -82,6 +94,7 @@ export const techdocsPlugin = createBackendPlugin({ await createRouter({ logger: winstonLogger, cache: cacheManager, + docsBuildStrategy, preparers, generators, publisher, diff --git a/plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts similarity index 96% rename from plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts rename to plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts index 84bd960f8f..7868135b08 100644 --- a/plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts +++ b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { DefaultDocsBuildStrategy } from './DocsBuildStrategy'; +import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy'; import { ConfigReader } from '@backstage/config'; const MockedConfigReader = ConfigReader as jest.MockedClass< diff --git a/plugins/techdocs-backend/src/service/DocsBuildStrategy.ts b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts similarity index 66% rename from plugins/techdocs-backend/src/service/DocsBuildStrategy.ts rename to plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts index 42a16234f9..fe0f5206ba 100644 --- a/plugins/techdocs-backend/src/service/DocsBuildStrategy.ts +++ b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts @@ -13,28 +13,13 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { Entity } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; +import { + DocsBuildStrategy, + ShouldBuildParameters, +} from '@backstage/plugin-techdocs-node'; -/** - * Parameters passed to the shouldBuild method on the DocsBuildStrategy interface - * - * @public - */ -export type ShouldBuildParameters = { - entity: Entity; -}; - -/** - * A strategy for when to build TechDocs locally, and when to skip building TechDocs (allowing for an external build) - * - * @public - */ -export interface DocsBuildStrategy { - shouldBuild(params: ShouldBuildParameters): Promise; -} - -export class DefaultDocsBuildStrategy { +export class DefaultDocsBuildStrategy implements DocsBuildStrategy { private readonly config: Config; private constructor(config: Config) { diff --git a/plugins/techdocs-backend/src/service/index.ts b/plugins/techdocs-backend/src/service/index.ts index 7355a34e32..0065e33a2a 100644 --- a/plugins/techdocs-backend/src/service/index.ts +++ b/plugins/techdocs-backend/src/service/index.ts @@ -20,7 +20,3 @@ export type { RecommendedDeploymentOptions, OutOfTheBoxDeploymentOptions, } from './router'; -export type { - DocsBuildStrategy, - ShouldBuildParameters, -} from './DocsBuildStrategy'; diff --git a/plugins/techdocs-backend/src/service/router.test.ts b/plugins/techdocs-backend/src/service/router.test.ts index 0c049c00f2..224a87cb43 100644 --- a/plugins/techdocs-backend/src/service/router.test.ts +++ b/plugins/techdocs-backend/src/service/router.test.ts @@ -22,6 +22,7 @@ import { } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; import { + DocsBuildStrategy, GeneratorBuilder, PreparerBuilder, PublisherBase, @@ -32,7 +33,6 @@ import { DocsSynchronizer, DocsSynchronizerSyncOpts } from './DocsSynchronizer'; import { CachedEntityLoader } from './CachedEntityLoader'; import { createEventStream, createRouter, RouterOptions } from './router'; import { TechDocsCache } from '../cache'; -import { DocsBuildStrategy } from './DocsBuildStrategy'; jest.mock('@backstage/catalog-client'); jest.mock('@backstage/config'); diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts index 855d8b02f4..734c1f40de 100644 --- a/plugins/techdocs-backend/src/service/router.ts +++ b/plugins/techdocs-backend/src/service/router.ts @@ -22,6 +22,7 @@ import { stringifyEntityRef } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; import { NotFoundError } from '@backstage/errors'; import { + DocsBuildStrategy, GeneratorBuilder, getLocationForEntity, PreparerBuilder, @@ -34,10 +35,7 @@ import { ScmIntegrations } from '@backstage/integration'; import { DocsSynchronizer, DocsSynchronizerSyncOpts } from './DocsSynchronizer'; import { createCacheMiddleware, TechDocsCache } from '../cache'; import { CachedEntityLoader } from './CachedEntityLoader'; -import { - DefaultDocsBuildStrategy, - DocsBuildStrategy, -} from './DocsBuildStrategy'; +import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy'; import * as winston from 'winston'; import { PassThrough } from 'stream'; diff --git a/plugins/techdocs-node/api-report.md b/plugins/techdocs-node/api-report.md index 656db6ae36..843190ceb8 100644 --- a/plugins/techdocs-node/api-report.md +++ b/plugins/techdocs-node/api-report.md @@ -10,6 +10,7 @@ import { Config } from '@backstage/config'; import { ContainerRunner } from '@backstage/backend-common'; import { Entity } from '@backstage/catalog-model'; import express from 'express'; +import { ExtensionPoint } from '@backstage/backend-plugin-api'; import { IndexableDocument } from '@backstage/plugin-search-common'; import { Logger } from 'winston'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; @@ -24,6 +25,12 @@ export class DirectoryPreparer implements PreparerBase { shouldCleanPreparedDirectory(): boolean; } +// @public +export interface DocsBuildStrategy { + // (undocumented) + shouldBuild(params: ShouldBuildParameters): Promise; +} + // @public export type ETag = string; @@ -226,9 +233,23 @@ export type ReadinessResponse = { // @public export type RemoteProtocol = 'url' | 'dir'; +// @public +export type ShouldBuildParameters = { + entity: Entity; +}; + // @public export type SupportedGeneratorKey = 'techdocs' | string; +// @public +export interface TechdocsBuildStrategyExtensionPoint { + // (undocumented) + setBuildStrategy(buildStrategy: DocsBuildStrategy): void; +} + +// @public +export const techdocsBuildStrategyExtensionPoint: ExtensionPoint; + // @public export interface TechDocsDocument extends IndexableDocument { kind: string; diff --git a/plugins/techdocs-node/package.json b/plugins/techdocs-node/package.json index 4ec11fde71..6258e7b9a3 100644 --- a/plugins/techdocs-node/package.json +++ b/plugins/techdocs-node/package.json @@ -47,6 +47,7 @@ "@azure/identity": "^3.2.1", "@azure/storage-blob": "^12.5.0", "@backstage/backend-common": "workspace:^", + "@backstage/backend-plugin-api": "workspace:^", "@backstage/catalog-model": "workspace:^", "@backstage/config": "workspace:^", "@backstage/errors": "workspace:^", diff --git a/plugins/techdocs-node/src/extensions.ts b/plugins/techdocs-node/src/extensions.ts new file mode 100644 index 0000000000..0de6fa1e27 --- /dev/null +++ b/plugins/techdocs-node/src/extensions.ts @@ -0,0 +1,36 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { createExtensionPoint } from '@backstage/backend-plugin-api'; +import { DocsBuildStrategy } from './techdocsTypes'; + +/** + * Extension point type for setting a custom build strategy. + * + * @public + */ +export interface TechdocsBuildStrategyExtensionPoint { + setBuildStrategy(buildStrategy: DocsBuildStrategy): void; +} + +/** + * Extension point for setting a custom build strategy. + * + * @public + */ +export const techdocsBuildStrategyExtensionPoint = + createExtensionPoint({ + id: 'techdocs.buildStrategy', + }); diff --git a/plugins/techdocs-node/src/index.ts b/plugins/techdocs-node/src/index.ts index a2acf84611..0c4b5bb67f 100644 --- a/plugins/techdocs-node/src/index.ts +++ b/plugins/techdocs-node/src/index.ts @@ -23,3 +23,7 @@ export * from './stages'; export * from './helpers'; export * from './techdocsTypes'; +export { + techdocsBuildStrategyExtensionPoint, + type TechdocsBuildStrategyExtensionPoint, +} from './extensions'; diff --git a/plugins/techdocs-node/src/techdocsTypes.ts b/plugins/techdocs-node/src/techdocsTypes.ts index 77436b35d5..6fc3ffc65f 100644 --- a/plugins/techdocs-node/src/techdocsTypes.ts +++ b/plugins/techdocs-node/src/techdocsTypes.ts @@ -14,6 +14,7 @@ * limitations under the License. */ +import { Entity } from '@backstage/catalog-model'; import { IndexableDocument } from '@backstage/plugin-search-common'; /** @@ -46,3 +47,21 @@ export interface TechDocsDocument extends IndexableDocument { */ path: string; } + +/** + * Parameters passed to the shouldBuild method on the DocsBuildStrategy interface + * + * @public + */ +export type ShouldBuildParameters = { + entity: Entity; +}; + +/** + * A strategy for when to build TechDocs locally, and when to skip building TechDocs (allowing for an external build) + * + * @public + */ +export interface DocsBuildStrategy { + shouldBuild(params: ShouldBuildParameters): Promise; +} diff --git a/yarn.lock b/yarn.lock index fd3b9da734..68ae329efc 100644 --- a/yarn.lock +++ b/yarn.lock @@ -9770,6 +9770,7 @@ __metadata: "@azure/identity": ^3.2.1 "@azure/storage-blob": ^12.5.0 "@backstage/backend-common": "workspace:^" + "@backstage/backend-plugin-api": "workspace:^" "@backstage/backend-test-utils": "workspace:^" "@backstage/catalog-model": "workspace:^" "@backstage/cli": "workspace:^" From 31458f5b639062bd6fad4588116c25ae6d572dd2 Mon Sep 17 00:00:00 2001 From: Phil Kuang Date: Mon, 16 Oct 2023 19:10:46 -0400 Subject: [PATCH 2/3] feat(techdocs): rename extension point Signed-off-by: Phil Kuang --- plugins/techdocs-backend/api-report.md | 21 ++++++++++++--------- plugins/techdocs-backend/src/index.ts | 25 +++++++++++++++++++------ plugins/techdocs-backend/src/plugin.ts | 4 ++-- plugins/techdocs-node/api-report.md | 4 ++-- plugins/techdocs-node/src/extensions.ts | 12 ++++++------ plugins/techdocs-node/src/index.ts | 4 ++-- 6 files changed, 43 insertions(+), 27 deletions(-) diff --git a/plugins/techdocs-backend/api-report.md b/plugins/techdocs-backend/api-report.md index 6e2fbc4c53..e449ddc459 100644 --- a/plugins/techdocs-backend/api-report.md +++ b/plugins/techdocs-backend/api-report.md @@ -7,7 +7,7 @@ import { CatalogApi } from '@backstage/catalog-client'; import { CatalogClient } from '@backstage/catalog-client'; import { Config } from '@backstage/config'; import { DefaultTechDocsCollatorFactory as DefaultTechDocsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-techdocs'; -import { DocsBuildStrategy } from '@backstage/plugin-techdocs-node'; +import { DocsBuildStrategy as DocsBuildStrategy_2 } from '@backstage/plugin-techdocs-node'; import express from 'express'; import { GeneratorBuilder } from '@backstage/plugin-techdocs-node'; import { Knex } from 'knex'; @@ -17,9 +17,9 @@ import { PluginCacheManager } from '@backstage/backend-common'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; import { PreparerBuilder } from '@backstage/plugin-techdocs-node'; import { PublisherBase } from '@backstage/plugin-techdocs-node'; -import { ShouldBuildParameters } from '@backstage/plugin-techdocs-node'; +import { ShouldBuildParameters as ShouldBuildParameters_2 } from '@backstage/plugin-techdocs-node'; import type { TechDocsCollatorFactoryOptions as TechDocsCollatorFactoryOptions_2 } from '@backstage/plugin-search-backend-module-techdocs'; -import { TechDocsDocument } from '@backstage/plugin-techdocs-node'; +import { TechDocsDocument as TechDocsDocument_2 } from '@backstage/plugin-techdocs-node'; import { TokenManager } from '@backstage/backend-common'; import * as winston from 'winston'; @@ -34,7 +34,7 @@ export class DefaultTechDocsCollator { args: Record, ): string; // (undocumented) - execute(): Promise; + execute(): Promise; // (undocumented) static fromConfig( config: Config, @@ -49,7 +49,8 @@ export class DefaultTechDocsCollator { // @public @deprecated (undocumented) export const DefaultTechDocsCollatorFactory: typeof DefaultTechDocsCollatorFactory_2; -export { DocsBuildStrategy }; +// @public @deprecated (undocumented) +export type DocsBuildStrategy = DocsBuildStrategy_2; // @public export type OutOfTheBoxDeploymentOptions = { @@ -61,7 +62,7 @@ export type OutOfTheBoxDeploymentOptions = { database?: Knex; config: Config; cache: PluginCacheManager; - docsBuildStrategy?: DocsBuildStrategy; + docsBuildStrategy?: DocsBuildStrategy_2; buildLogTransport?: winston.transport; catalogClient?: CatalogClient; }; @@ -73,7 +74,7 @@ export type RecommendedDeploymentOptions = { discovery: PluginEndpointDiscovery; config: Config; cache: PluginCacheManager; - docsBuildStrategy?: DocsBuildStrategy; + docsBuildStrategy?: DocsBuildStrategy_2; buildLogTransport?: winston.transport; catalogClient?: CatalogClient; }; @@ -83,7 +84,8 @@ export type RouterOptions = | RecommendedDeploymentOptions | OutOfTheBoxDeploymentOptions; -export { ShouldBuildParameters }; +// @public @deprecated (undocumented) +export type ShouldBuildParameters = ShouldBuildParameters_2; // @public @deprecated (undocumented) export type TechDocsCollatorFactoryOptions = TechDocsCollatorFactoryOptions_2; @@ -99,7 +101,8 @@ export type TechDocsCollatorOptions = { legacyPathCasing?: boolean; }; -export { TechDocsDocument }; +// @public @deprecated (undocumented) +export type TechDocsDocument = TechDocsDocument_2; export * from '@backstage/plugin-techdocs-node'; ``` diff --git a/plugins/techdocs-backend/src/index.ts b/plugins/techdocs-backend/src/index.ts index cf70db39e8..f9634528f9 100644 --- a/plugins/techdocs-backend/src/index.ts +++ b/plugins/techdocs-backend/src/index.ts @@ -20,6 +20,12 @@ * @packageDocumentation */ +import { + DocsBuildStrategy as _DocsBuildStrategy, + ShouldBuildParameters as _ShouldBuildParameters, + TechDocsDocument as _TechDocsDocument, +} from '@backstage/plugin-techdocs-node'; + export { createRouter } from './service'; export type { RouterOptions, @@ -37,12 +43,19 @@ export type { } from './search'; /** - * @deprecated Use directly from @backstage/plugin-techdocs-node + * @public + * @deprecated import from `@backstage/plugin-techdocs-node` instead */ -export type { - DocsBuildStrategy, - ShouldBuildParameters, - TechDocsDocument, -} from '@backstage/plugin-techdocs-node'; +export type DocsBuildStrategy = _DocsBuildStrategy; +/** + * @public + * @deprecated import from `@backstage/plugin-techdocs-node` instead + */ +export type ShouldBuildParameters = _ShouldBuildParameters; +/** + * @public + * @deprecated import from `@backstage/plugin-techdocs-node` instead + */ +export type TechDocsDocument = _TechDocsDocument; export * from '@backstage/plugin-techdocs-node'; diff --git a/plugins/techdocs-backend/src/plugin.ts b/plugins/techdocs-backend/src/plugin.ts index 2dcde1a975..f139cf3c3a 100644 --- a/plugins/techdocs-backend/src/plugin.ts +++ b/plugins/techdocs-backend/src/plugin.ts @@ -29,7 +29,7 @@ import { Preparers, Generators, Publisher, - techdocsBuildStrategyExtensionPoint, + techdocsBuildsExtensionPoint, } from '@backstage/plugin-techdocs-node'; import Docker from 'dockerode'; import { createRouter } from '@backstage/plugin-techdocs-backend'; @@ -42,7 +42,7 @@ export const techdocsPlugin = createBackendPlugin({ pluginId: 'techdocs', register(env) { let docsBuildStrategy: DocsBuildStrategy | undefined; - env.registerExtensionPoint(techdocsBuildStrategyExtensionPoint, { + env.registerExtensionPoint(techdocsBuildsExtensionPoint, { setBuildStrategy(buildStrategy: DocsBuildStrategy) { if (docsBuildStrategy) { throw new Error('DocsBuildStrategy may only be set once'); diff --git a/plugins/techdocs-node/api-report.md b/plugins/techdocs-node/api-report.md index 843190ceb8..3ce422cbc5 100644 --- a/plugins/techdocs-node/api-report.md +++ b/plugins/techdocs-node/api-report.md @@ -242,13 +242,13 @@ export type ShouldBuildParameters = { export type SupportedGeneratorKey = 'techdocs' | string; // @public -export interface TechdocsBuildStrategyExtensionPoint { +export interface TechdocsBuildsExtensionPoint { // (undocumented) setBuildStrategy(buildStrategy: DocsBuildStrategy): void; } // @public -export const techdocsBuildStrategyExtensionPoint: ExtensionPoint; +export const techdocsBuildsExtensionPoint: ExtensionPoint; // @public export interface TechDocsDocument extends IndexableDocument { diff --git a/plugins/techdocs-node/src/extensions.ts b/plugins/techdocs-node/src/extensions.ts index 0de6fa1e27..c3a048b4e2 100644 --- a/plugins/techdocs-node/src/extensions.ts +++ b/plugins/techdocs-node/src/extensions.ts @@ -17,20 +17,20 @@ import { createExtensionPoint } from '@backstage/backend-plugin-api'; import { DocsBuildStrategy } from './techdocsTypes'; /** - * Extension point type for setting a custom build strategy. + * Extension point type for configuring Techdocs builds. * * @public */ -export interface TechdocsBuildStrategyExtensionPoint { +export interface TechdocsBuildsExtensionPoint { setBuildStrategy(buildStrategy: DocsBuildStrategy): void; } /** - * Extension point for setting a custom build strategy. + * Extension point for configuring Techdocs builds. * * @public */ -export const techdocsBuildStrategyExtensionPoint = - createExtensionPoint({ - id: 'techdocs.buildStrategy', +export const techdocsBuildsExtensionPoint = + createExtensionPoint({ + id: 'techdocs.builds', }); diff --git a/plugins/techdocs-node/src/index.ts b/plugins/techdocs-node/src/index.ts index 0c4b5bb67f..640bd09ce0 100644 --- a/plugins/techdocs-node/src/index.ts +++ b/plugins/techdocs-node/src/index.ts @@ -24,6 +24,6 @@ export * from './stages'; export * from './helpers'; export * from './techdocsTypes'; export { - techdocsBuildStrategyExtensionPoint, - type TechdocsBuildStrategyExtensionPoint, + techdocsBuildsExtensionPoint, + type TechdocsBuildsExtensionPoint, } from './extensions'; From b99e29ab8fa22da9d6a04dfacf3937037591792a Mon Sep 17 00:00:00 2001 From: Phil Kuang Date: Tue, 24 Oct 2023 13:06:05 -0400 Subject: [PATCH 3/3] refactor(techdocs): deprecate ShouldBuildParameters type Signed-off-by: Phil Kuang --- .changeset/two-jars-melt.md | 2 +- plugins/techdocs-backend/api-report.md | 6 ++++-- plugins/techdocs-backend/src/index.ts | 8 +++++--- .../src/service/DefaultDocsBuildStrategy.ts | 8 +++----- plugins/techdocs-node/api-report.md | 7 +------ plugins/techdocs-node/src/techdocsTypes.ts | 11 +---------- 6 files changed, 15 insertions(+), 27 deletions(-) diff --git a/.changeset/two-jars-melt.md b/.changeset/two-jars-melt.md index d6f0166885..2789157065 100644 --- a/.changeset/two-jars-melt.md +++ b/.changeset/two-jars-melt.md @@ -3,4 +3,4 @@ '@backstage/plugin-techdocs-node': minor --- -Expose an extension point to set a custom build strategy and move `DocsBuildStrategy` and `ShouldBuildParameters` types to `@backstage/plugin-techdocs-node` +Expose an extension point to set a custom build strategy. Also move `DocsBuildStrategy` type to `@backstage/plugin-techdocs-node` and deprecate `ShouldBuildParameters` type. diff --git a/plugins/techdocs-backend/api-report.md b/plugins/techdocs-backend/api-report.md index e449ddc459..9e9a42c388 100644 --- a/plugins/techdocs-backend/api-report.md +++ b/plugins/techdocs-backend/api-report.md @@ -8,6 +8,7 @@ import { CatalogClient } from '@backstage/catalog-client'; import { Config } from '@backstage/config'; import { DefaultTechDocsCollatorFactory as DefaultTechDocsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-techdocs'; import { DocsBuildStrategy as DocsBuildStrategy_2 } from '@backstage/plugin-techdocs-node'; +import { Entity } from '@backstage/catalog-model'; import express from 'express'; import { GeneratorBuilder } from '@backstage/plugin-techdocs-node'; import { Knex } from 'knex'; @@ -17,7 +18,6 @@ import { PluginCacheManager } from '@backstage/backend-common'; import { PluginEndpointDiscovery } from '@backstage/backend-common'; import { PreparerBuilder } from '@backstage/plugin-techdocs-node'; import { PublisherBase } from '@backstage/plugin-techdocs-node'; -import { ShouldBuildParameters as ShouldBuildParameters_2 } from '@backstage/plugin-techdocs-node'; import type { TechDocsCollatorFactoryOptions as TechDocsCollatorFactoryOptions_2 } from '@backstage/plugin-search-backend-module-techdocs'; import { TechDocsDocument as TechDocsDocument_2 } from '@backstage/plugin-techdocs-node'; import { TokenManager } from '@backstage/backend-common'; @@ -85,7 +85,9 @@ export type RouterOptions = | OutOfTheBoxDeploymentOptions; // @public @deprecated (undocumented) -export type ShouldBuildParameters = ShouldBuildParameters_2; +export type ShouldBuildParameters = { + entity: Entity; +}; // @public @deprecated (undocumented) export type TechDocsCollatorFactoryOptions = TechDocsCollatorFactoryOptions_2; diff --git a/plugins/techdocs-backend/src/index.ts b/plugins/techdocs-backend/src/index.ts index f9634528f9..6dc68a4d44 100644 --- a/plugins/techdocs-backend/src/index.ts +++ b/plugins/techdocs-backend/src/index.ts @@ -20,9 +20,9 @@ * @packageDocumentation */ +import { Entity } from '@backstage/catalog-model'; import { DocsBuildStrategy as _DocsBuildStrategy, - ShouldBuildParameters as _ShouldBuildParameters, TechDocsDocument as _TechDocsDocument, } from '@backstage/plugin-techdocs-node'; @@ -49,9 +49,11 @@ export type { export type DocsBuildStrategy = _DocsBuildStrategy; /** * @public - * @deprecated import from `@backstage/plugin-techdocs-node` instead + * @deprecated use direct type definition instead */ -export type ShouldBuildParameters = _ShouldBuildParameters; +export type ShouldBuildParameters = { + entity: Entity; +}; /** * @public * @deprecated import from `@backstage/plugin-techdocs-node` instead diff --git a/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts index fe0f5206ba..bc2c586c82 100644 --- a/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts +++ b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts @@ -13,11 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { Entity } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; -import { - DocsBuildStrategy, - ShouldBuildParameters, -} from '@backstage/plugin-techdocs-node'; +import { DocsBuildStrategy } from '@backstage/plugin-techdocs-node'; export class DefaultDocsBuildStrategy implements DocsBuildStrategy { private readonly config: Config; @@ -30,7 +28,7 @@ export class DefaultDocsBuildStrategy implements DocsBuildStrategy { return new DefaultDocsBuildStrategy(config); } - async shouldBuild(_: ShouldBuildParameters): Promise { + async shouldBuild(_: { entity: Entity }): Promise { return this.config.getString('techdocs.builder') === 'local'; } } diff --git a/plugins/techdocs-node/api-report.md b/plugins/techdocs-node/api-report.md index 3ce422cbc5..c267574642 100644 --- a/plugins/techdocs-node/api-report.md +++ b/plugins/techdocs-node/api-report.md @@ -28,7 +28,7 @@ export class DirectoryPreparer implements PreparerBase { // @public export interface DocsBuildStrategy { // (undocumented) - shouldBuild(params: ShouldBuildParameters): Promise; + shouldBuild(params: { entity: Entity }): Promise; } // @public @@ -233,11 +233,6 @@ export type ReadinessResponse = { // @public export type RemoteProtocol = 'url' | 'dir'; -// @public -export type ShouldBuildParameters = { - entity: Entity; -}; - // @public export type SupportedGeneratorKey = 'techdocs' | string; diff --git a/plugins/techdocs-node/src/techdocsTypes.ts b/plugins/techdocs-node/src/techdocsTypes.ts index 6fc3ffc65f..6a5ee522e1 100644 --- a/plugins/techdocs-node/src/techdocsTypes.ts +++ b/plugins/techdocs-node/src/techdocsTypes.ts @@ -48,20 +48,11 @@ export interface TechDocsDocument extends IndexableDocument { path: string; } -/** - * Parameters passed to the shouldBuild method on the DocsBuildStrategy interface - * - * @public - */ -export type ShouldBuildParameters = { - entity: Entity; -}; - /** * A strategy for when to build TechDocs locally, and when to skip building TechDocs (allowing for an external build) * * @public */ export interface DocsBuildStrategy { - shouldBuild(params: ShouldBuildParameters): Promise; + shouldBuild(params: { entity: Entity }): Promise; }