Merge pull request #20576 from kuangp/feat/buildStrategyExtension

feat(techdocs): add extension for setting build strategy

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: { entity: Entity }): Promise<boolean>;
+}
+
 // @public
 export type ETag = string;
 
@@ -229,6 +236,15 @@ export type RemoteProtocol = 'url' | 'dir';
 // @public
 export type SupportedGeneratorKey = 'techdocs' | string;
 
+// @public
+export interface TechdocsBuildsExtensionPoint {
+  // (undocumented)
+  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;
+}
+
+// @public
+export const techdocsBuildsExtensionPoint: ExtensionPoint<TechdocsBuildsExtensionPoint>;
+
 // @public
 export interface TechDocsDocument extends IndexableDocument {
   kind: string;

plugins/techdocs-node/package.json

@@ -46,6 +46,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:^",

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 configuring Techdocs builds.
+ *
+ * @public
+ */
+export interface TechdocsBuildsExtensionPoint {
+  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;
+}
+
+/**
+ * Extension point for configuring Techdocs builds.
+ *
+ * @public
+ */
+export const techdocsBuildsExtensionPoint =
+  createExtensionPoint<TechdocsBuildsExtensionPoint>({
+    id: 'techdocs.builds',
+  });

plugins/techdocs-node/src/index.ts

@@ -23,3 +23,7 @@
 export * from './stages';
 export * from './helpers';
 export * from './techdocsTypes';
+export {
+  techdocsBuildsExtensionPoint,
+  type TechdocsBuildsExtensionPoint,
+} from './extensions';

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,12 @@ export interface TechDocsDocument extends IndexableDocument {
    */
   path: string;
 }
+
+/**
+ * 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: { entity: Entity }): Promise<boolean>;
+}