paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

TechDocs legacy

Browse Source 
Signed-off-by: Andre Wanlin <awanlin@spotify.com>
This commit is contained in:
Andre Wanlin
2025-03-14 15:02:20 -05:00
parent d5c4a9db09
commit 7a2cfbbd31
13 changed files with 40 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/four-months-beg.md
+1 -1
View File
@@ -2,4 +2,4 @@
'@backstage/plugin-techdocs-backend': major
---
**BREAKING** Removed deprecated code `DefaultTechDocsCollatorFactory`. Use the `@backstage/plugin-search-backend-module-techdocs` for this instead.
**BREAKING** Removed support for the legacy backend, please migrate to the new backend system. Also removed deprecated `DefaultTechDocsCollatorFactory`. Use the `@backstage/plugin-search-backend-module-techdocs` for this instead. Finally, deprecated `DocsBuildStrategy` and `TechDocsDocument` were removed, use the versions in `@backstage/plugin-techdocs-node` instead.
packages/backend-legacy/src/index.ts
-3
View File
@@ -43,7 +43,6 @@ import catalog from './plugins/catalog';
import events from './plugins/events';
import kubernetes from './plugins/kubernetes';
import scaffolder from './plugins/scaffolder';
import techdocs from './plugins/techdocs';
import permission from './plugins/permission';
import { PluginEnvironment } from './types';
import { ServerPermissionClient } from '@backstage/plugin-permission-node';
@@ -132,7 +131,6 @@ async function main() {
const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
const scaffolderEnv = useHotMemoize(module, () => createEnv('scaffolder'));
const authEnv = useHotMemoize(module, () => createEnv('auth'));
const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs'));
const kubernetesEnv = useHotMemoize(module, () => createEnv('kubernetes'));
const permissionEnv = useHotMemoize(module, () => createEnv('permission'));
const eventsEnv = useHotMemoize(module, () => createEnv('events'));
@@ -142,7 +140,6 @@ async function main() {
apiRouter.use('/events', await events(eventsEnv));
apiRouter.use('/scaffolder', await scaffolder(scaffolderEnv));
apiRouter.use('/auth', await authPlugin(authEnv));
apiRouter.use('/techdocs', await techdocs(techdocsEnv));
apiRouter.use('/kubernetes', await kubernetes(kubernetesEnv));
apiRouter.use('/permission', await permission(permissionEnv));
apiRouter.use(notFoundHandler());
packages/backend-legacy/src/plugins/techdocs.ts
-60
View File
@@ -1,60 +0,0 @@
/*
* Copyright 2020 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 {
createRouter,
Generators,
Preparers,
Publisher,
} from '@backstage/plugin-techdocs-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
// Preparers are responsible for fetching source files for documentation.
const preparers = await Preparers.fromConfig(env.config, {
logger: env.logger,
reader: env.reader,
});
// Generators are used for generating documentation sites.
const generators = await Generators.fromConfig(env.config, {
logger: env.logger,
});
// Publisher is used for
// 1. Publishing generated files to storage
// 2. Fetching files from storage and passing them to TechDocs frontend.
const publisher = await Publisher.fromConfig(env.config, {
logger: env.logger,
discovery: env.discovery,
});
// checks if the publisher is working and logs the result
await publisher.getReadiness();
return await createRouter({
preparers,
generators,
publisher,
logger: env.logger,
config: env.config,
discovery: env.discovery,
cache: env.cache,
});
}
plugins/techdocs-backend/package.json
+1 -1
View File
@@ -58,7 +58,7 @@
"test": "backstage-cli package test"
},
"dependencies": {
"@backstage/backend-common": "^0.25.0",
"@backstage/backend-defaults": "workspace:^",
"@backstage/backend-plugin-api": "workspace:^",
"@backstage/catalog-client": "workspace:^",
"@backstage/catalog-model": "workspace:^",
plugins/techdocs-backend/report.api.md
-67
View File
@@ -3,76 +3,9 @@
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
```ts
import { AuthService } from '@backstage/backend-plugin-api';
import { BackendFeature } from '@backstage/backend-plugin-api';
import { CatalogApi } from '@backstage/catalog-client';
import { Config } from '@backstage/config';
import { DiscoveryService } from '@backstage/backend-plugin-api';
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 { HttpAuthService } from '@backstage/backend-plugin-api';
import { Knex } from 'knex';
import { PluginCacheManager } from '@backstage/backend-common';
import { PreparerBuilder } from '@backstage/plugin-techdocs-node';
import { PublisherBase } from '@backstage/plugin-techdocs-node';
import { TechDocsDocument as TechDocsDocument_2 } from '@backstage/plugin-techdocs-node';
import * as winston from 'winston';
// @public @deprecated
export function createRouter(options: RouterOptions): Promise<express.Router>;
// @public @deprecated (undocumented)
export type DocsBuildStrategy = DocsBuildStrategy_2;
// @public
export type OutOfTheBoxDeploymentOptions = {
preparers: PreparerBuilder;
generators: GeneratorBuilder;
publisher: PublisherBase;
logger: winston.Logger;
discovery: DiscoveryService;
database?: Knex;
config: Config;
cache: PluginCacheManager;
docsBuildStrategy?: DocsBuildStrategy_2;
buildLogTransport?: winston.transport;
catalogClient?: CatalogApi;
httpAuth?: HttpAuthService;
auth?: AuthService;
};
// @public @deprecated
export type RecommendedDeploymentOptions = {
publisher: PublisherBase;
logger: winston.Logger;
discovery: DiscoveryService;
config: Config;
cache: PluginCacheManager;
docsBuildStrategy?: DocsBuildStrategy_2;
buildLogTransport?: winston.transport;
catalogClient?: CatalogApi;
httpAuth?: HttpAuthService;
auth?: AuthService;
};
// @public @deprecated
export type RouterOptions =
| RecommendedDeploymentOptions
| OutOfTheBoxDeploymentOptions;
// @public @deprecated (undocumented)
export type ShouldBuildParameters = {
entity: Entity;
};
// @public @deprecated (undocumented)
export type TechDocsDocument = TechDocsDocument_2;
// @public
const techdocsPlugin: BackendFeature;
export default techdocsPlugin;
export * from '@backstage/plugin-techdocs-node';
```
plugins/techdocs-backend/src/index.ts
-32
View File
@@ -20,36 +20,4 @@
* @packageDocumentation
*/
import { Entity } from '@backstage/catalog-model';
import {
DocsBuildStrategy as _DocsBuildStrategy,
TechDocsDocument as _TechDocsDocument,
} from '@backstage/plugin-techdocs-node';
export { techdocsPlugin as default } from './plugin';
export { createRouter } from './service';
export type {
RouterOptions,
RecommendedDeploymentOptions,
OutOfTheBoxDeploymentOptions,
} from './service';
/**
* @public
* @deprecated import from `@backstage/plugin-techdocs-node` instead
*/
export type DocsBuildStrategy = _DocsBuildStrategy;
/**
* @public
* @deprecated use direct type definition instead
*/
export type ShouldBuildParameters = {
entity: Entity;
};
/**
* @public
* @deprecated import from `@backstage/plugin-techdocs-node` instead
*/
export type TechDocsDocument = _TechDocsDocument;
export * from '@backstage/plugin-techdocs-node';
plugins/techdocs-backend/src/plugin.ts
+6 -12
View File
@@ -14,10 +14,6 @@
* limitations under the License.
*/
import {
cacheToPluginCacheManager,
loggerToWinstonLogger,
} from '@backstage/backend-common';
import {
coreServices,
createBackendPlugin,
@@ -38,9 +34,9 @@ import {
techdocsPreparerExtensionPoint,
techdocsPublisherExtensionPoint,
} from '@backstage/plugin-techdocs-node';
import { createRouter } from './service';
import { catalogServiceRef } from '@backstage/plugin-catalog-node/alpha';
import * as winston from 'winston';
import { createRouter } from './service/router';
/**
* The TechDocs plugin is responsible for serving and building documentation for any entity.
@@ -129,11 +125,10 @@ export const techdocsPlugin = createBackendPlugin({
auth,
catalog,
}) {
const winstonLogger = loggerToWinstonLogger(logger);
// Preparers are responsible for fetching source files for documentation.
const preparers = await Preparers.fromConfig(config, {
reader: urlReader,
logger: winstonLogger,
logger: logger,
});
for (const [protocol, preparer] of customPreparers.entries()) {
preparers.register(protocol, preparer);
@@ -141,7 +136,7 @@ export const techdocsPlugin = createBackendPlugin({
// Generators are used for generating documentation sites.
const generators = await Generators.fromConfig(config, {
logger: winstonLogger,
logger: logger,
customGenerator: customTechdocsGenerator,
});
@@ -149,7 +144,7 @@ export const techdocsPlugin = createBackendPlugin({
// 1. Publishing generated files to storage
// 2. Fetching files from storage and passing them to TechDocs frontend.
const publisher = await Publisher.fromConfig(config, {
logger: winstonLogger,
logger: logger,
discovery: discovery,
customPublisher: customTechdocsPublisher,
publisherSettings,
@@ -158,11 +153,10 @@ export const techdocsPlugin = createBackendPlugin({
// checks if the publisher is working and logs the result
await publisher.getReadiness();
const cacheManager = cacheToPluginCacheManager(cache);
http.use(
await createRouter({
logger: winstonLogger,
cache: cacheManager,
logger: logger,
cache,
docsBuildStrategy,
buildLogTransport,
preparers,
plugins/techdocs-backend/src/service/DocsSynchronizer.test.ts
+2 -3
View File
@@ -14,7 +14,6 @@
* limitations under the License.
*/
import { loggerToWinstonLogger } from '@backstage/backend-common';
import { ConfigReader } from '@backstage/config';
import { ScmIntegrations } from '@backstage/integration';
import {
@@ -87,7 +86,7 @@ describe('DocsSynchronizer', () => {
docsSynchronizer = new DocsSynchronizer({
publisher,
config: new ConfigReader({}),
logger: loggerToWinstonLogger(mockServices.logger.mock()),
logger: mockServices.logger.mock(),
buildLogTransport: mockBuildLogTransport,
scmIntegrations: ScmIntegrations.fromConfig(new ConfigReader({})),
cache,
@@ -343,7 +342,7 @@ describe('DocsSynchronizer', () => {
config: new ConfigReader({
techdocs: { legacyUseCaseSensitiveTripletPaths: true },
}),
logger: loggerToWinstonLogger(mockServices.logger.mock()),
logger: mockServices.logger.mock(),
buildLogTransport: new winston.transports.Stream({
stream: new PassThrough(),
}),
plugins/techdocs-backend/src/service/DocsSynchronizer.ts
+3 -3
View File
@@ -36,7 +36,7 @@ import {
DocsBuilder,
shouldCheckForUpdate,
} from '../DocsBuilder';
import { DiscoveryService } from '@backstage/backend-plugin-api';
import { DiscoveryService, LoggerService } from '@backstage/backend-plugin-api';
export type DocsSynchronizerSyncOpts = {
log: (message: string) => void;
@@ -46,7 +46,7 @@ export type DocsSynchronizerSyncOpts = {
export class DocsSynchronizer {
private readonly publisher: PublisherBase;
private readonly logger: winston.Logger;
private readonly logger: LoggerService;
private readonly buildLogTransport?: winston.transport;
private readonly config: Config;
private readonly scmIntegrations: ScmIntegrationRegistry;
@@ -62,7 +62,7 @@ export class DocsSynchronizer {
cache,
}: {
publisher: PublisherBase;
logger: winston.Logger;
logger: LoggerService;
buildLogTransport?: winston.transport;
config: Config;
scmIntegrations: ScmIntegrationRegistry;
plugins/techdocs-backend/src/service/index.ts
-22
View File
@@ -1,22 +0,0 @@
/*
* Copyright 2022 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.
*/
export { createRouter } from './router';
export type {
RouterOptions,
RecommendedDeploymentOptions,
OutOfTheBoxDeploymentOptions,
} from './router';
plugins/techdocs-backend/src/service/router.test.ts
+9 -11
View File
@@ -14,10 +14,6 @@
* limitations under the License.
*/
import {
PluginCacheManager,
loggerToWinstonLogger,
} from '@backstage/backend-common';
import { ConfigReader } from '@backstage/config';
import {
DocsBuildStrategy,
@@ -111,9 +107,7 @@ describe('createRouter', () => {
publish: jest.fn(),
};
const discovery = mockServices.discovery.mock();
const cache: jest.Mocked<PluginCacheManager> = {
getClient: jest.fn(),
};
const docsBuildStrategy: jest.Mocked<DocsBuildStrategy> = {
shouldBuild: jest.fn(),
};
@@ -122,18 +116,22 @@ describe('createRouter', () => {
generators,
publisher,
config: new ConfigReader({}),
logger: loggerToWinstonLogger(mockServices.logger.mock()),
logger: mockServices.logger.mock(),
discovery,
cache,
cache: mockServices.cache.mock(),
docsBuildStrategy,
auth: mockServices.auth(),
httpAuth: mockServices.httpAuth(),
};
const recommendedOptions = {
publisher,
config: new ConfigReader({}),
logger: loggerToWinstonLogger(mockServices.logger.mock()),
logger: mockServices.logger.mock(),
discovery,
cache,
cache: mockServices.cache.mock(),
docsBuildStrategy,
auth: mockServices.auth(),
httpAuth: mockServices.httpAuth(),
};
beforeEach(() => {
plugins/techdocs-backend/src/service/router.ts
+18 -26
View File
@@ -14,10 +14,6 @@
* limitations under the License.
*/
import {
createLegacyAuthAdapters,
PluginCacheManager,
} from '@backstage/backend-common';
import { CatalogApi, CatalogClient } from '@backstage/catalog-client';
import { stringifyEntityRef } from '@backstage/catalog-model';
import { Config } from '@backstage/config';
@@ -40,57 +36,57 @@ import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy';
import * as winston from 'winston';
import {
AuthService,
CacheService,
DiscoveryService,
HttpAuthService,
LoggerService,
} from '@backstage/backend-plugin-api';
/**
* Required dependencies for running TechDocs in the "out-of-the-box"
* deployment configuration (prepare/generate/publish all in the Backend).
*
* @public
* @internal
*/
export type OutOfTheBoxDeploymentOptions = {
preparers: PreparerBuilder;
generators: GeneratorBuilder;
publisher: PublisherBase;
logger: winston.Logger;
logger: LoggerService;
discovery: DiscoveryService;
database?: Knex; // TODO: Make database required when we're implementing database stuff.
config: Config;
cache: PluginCacheManager;
cache: CacheService;
docsBuildStrategy?: DocsBuildStrategy;
buildLogTransport?: winston.transport;
catalogClient?: CatalogApi;
httpAuth?: HttpAuthService;
auth?: AuthService;
httpAuth: HttpAuthService;
auth: AuthService;
};
/**
* Required dependencies for running TechDocs in the "recommended" deployment
* configuration (prepare/generate handled externally in CI/CD).
*
* @public
* @deprecated This type is only exported for legacy reasons and will be removed in the future.
* @internal
*/
export type RecommendedDeploymentOptions = {
publisher: PublisherBase;
logger: winston.Logger;
logger: LoggerService;
discovery: DiscoveryService;
config: Config;
cache: PluginCacheManager;
cache: CacheService;
docsBuildStrategy?: DocsBuildStrategy;
buildLogTransport?: winston.transport;
catalogClient?: CatalogApi;
httpAuth?: HttpAuthService;
auth?: AuthService;
httpAuth: HttpAuthService;
auth: AuthService;
};
/**
* One of the two deployment configurations must be provided.
*
* @public
* @deprecated This type is only exported for legacy reasons and will be removed in the future.
* @internal
*/
export type RouterOptions =
| RecommendedDeploymentOptions
@@ -100,7 +96,7 @@ export type RouterOptions =
* Typeguard to help createRouter() understand when we are in a "recommended"
* deployment vs. when we are in an out-of-the-box deployment configuration.
*
* @public
* @internal
*/
function isOutOfTheBoxOption(
opt: RouterOptions,
@@ -111,17 +107,13 @@ function isOutOfTheBoxOption(
/**
* Creates a techdocs router.
*
* @public
* @deprecated This function is only exported for legacy reasons and will be removed in the future.
* Please {@link https://backstage.io/docs/backend-system/building-backends/migrating | migrate } to use the new backend system and follow these {@link https://backstage.io/docs/features/techdocs/getting-started#new-backend-system | instructions } to install the user settings backend plugin.
* @internal
*/
export async function createRouter(
options: RouterOptions,
): Promise<express.Router> {
const router = Router();
const { publisher, config, logger, discovery } = options;
const { auth, httpAuth } = createLegacyAuthAdapters(options);
const { publisher, config, logger, discovery, httpAuth, auth } = options;
const catalogClient =
options.catalogClient ?? new CatalogClient({ discoveryApi: discovery });
@@ -133,14 +125,14 @@ export async function createRouter(
// when loading a single techdocs page.
const entityLoader = new CachedEntityLoader({
catalog: catalogClient,
cache: options.cache.getClient(),
cache: options.cache,
});
// Set up a cache client if configured.
let cache: TechDocsCache | undefined;
const defaultTtl = config.getOptionalNumber('techdocs.cache.ttl');
if (defaultTtl) {
const cacheClient = options.cache.getClient({ defaultTtl });
const cacheClient = options.cache.withOptions({ defaultTtl });
cache = TechDocsCache.fromConfig(config, { cache: cacheClient, logger });
}
yarn.lock
-1
View File
@@ -8450,7 +8450,6 @@ __metadata:
version: 0.0.0-use.local
resolution: "@backstage/plugin-techdocs-backend@workspace:plugins/techdocs-backend"
dependencies:
"@backstage/backend-common": ^0.25.0
"@backstage/backend-defaults": "workspace:^"
"@backstage/backend-plugin-api": "workspace:^"
"@backstage/backend-test-utils": "workspace:^"