diff --git a/.changeset/large-feet-wash.md b/.changeset/large-feet-wash.md new file mode 100644 index 0000000000..88a28f9d60 --- /dev/null +++ b/.changeset/large-feet-wash.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs-backend': minor +--- + +Introduced alpha export of the `techdocsPlugin` using the new backend system. diff --git a/packages/backend-next/package.json b/packages/backend-next/package.json index 9f7ec8306a..5d8a8cb1ec 100644 --- a/packages/backend-next/package.json +++ b/packages/backend-next/package.json @@ -29,6 +29,7 @@ "@backstage/plugin-app-backend": "workspace:^", "@backstage/plugin-catalog-backend": "workspace:^", "@backstage/plugin-scaffolder-backend": "workspace:^", + "@backstage/plugin-techdocs-backend": "workspace:^", "@backstage/plugin-todo-backend": "workspace:^" }, "devDependencies": { diff --git a/packages/backend-next/src/index.ts b/packages/backend-next/src/index.ts index 8e29244ebf..8f8984b192 100644 --- a/packages/backend-next/src/index.ts +++ b/packages/backend-next/src/index.ts @@ -19,6 +19,7 @@ import { catalogModuleTemplateKind } from '@backstage/plugin-scaffolder-backend/ import { createBackend } from '@backstage/backend-defaults'; import { appPlugin } from '@backstage/plugin-app-backend/alpha'; import { todoPlugin } from '@backstage/plugin-todo-backend'; +import { techdocsPlugin } from '@backstage/plugin-techdocs-backend/alpha'; const backend = createBackend(); @@ -26,4 +27,5 @@ backend.add(catalogPlugin()); backend.add(catalogModuleTemplateKind()); backend.add(appPlugin({ appPackageName: 'example-app' })); backend.add(todoPlugin()); +backend.add(techdocsPlugin()); backend.start(); diff --git a/plugins/techdocs-backend/alpha-api-report.md b/plugins/techdocs-backend/alpha-api-report.md new file mode 100644 index 0000000000..16db84c216 --- /dev/null +++ b/plugins/techdocs-backend/alpha-api-report.md @@ -0,0 +1,12 @@ +## API Report File for "@backstage/plugin-techdocs-backend" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts +import { BackendFeature } from '@backstage/backend-plugin-api'; + +// @alpha +export const techdocsPlugin: () => BackendFeature; + +// (No @packageDocumentation comment for this package) +``` diff --git a/plugins/techdocs-backend/package.json b/plugins/techdocs-backend/package.json index c9fff25b70..1d2f4400eb 100644 --- a/plugins/techdocs-backend/package.json +++ b/plugins/techdocs-backend/package.json @@ -10,6 +10,21 @@ "main": "dist/index.cjs.js", "types": "dist/index.d.ts" }, + "exports": { + ".": "./src/index.ts", + "./alpha": "./src/alpha.ts", + "./package.json": "./package.json" + }, + "typesVersions": { + "*": { + "alpha": [ + "src/alpha.ts" + ], + "package.json": [ + "package.json" + ] + } + }, "backstage": { "role": "backend-plugin" }, @@ -34,6 +49,7 @@ }, "dependencies": { "@backstage/backend-common": "workspace:^", + "@backstage/backend-plugin-api": "workspace:^", "@backstage/catalog-client": "workspace:^", "@backstage/catalog-model": "workspace:^", "@backstage/config": "workspace:^", diff --git a/plugins/techdocs-backend/src/alpha.ts b/plugins/techdocs-backend/src/alpha.ts new file mode 100644 index 0000000000..1a36c5a1f5 --- /dev/null +++ b/plugins/techdocs-backend/src/alpha.ts @@ -0,0 +1,16 @@ +/* + * 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. + */ +export { techdocsPlugin } from './plugin'; diff --git a/plugins/techdocs-backend/src/plugin.ts b/plugins/techdocs-backend/src/plugin.ts new file mode 100644 index 0000000000..134de2bba6 --- /dev/null +++ b/plugins/techdocs-backend/src/plugin.ts @@ -0,0 +1,95 @@ +/* + * 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 { + DockerContainerRunner, + loggerToWinstonLogger, + cacheToPluginCacheManager, +} from '@backstage/backend-common'; +import { + coreServices, + createBackendPlugin, +} from '@backstage/backend-plugin-api'; + +import { + Preparers, + Generators, + Publisher, +} from '@backstage/plugin-techdocs-node'; +import Docker from 'dockerode'; +import { createRouter } from '@backstage/plugin-techdocs-backend'; + +/** + * The TechDocs plugin is responsible for serving and building documentation for any entity. + * @alpha + */ +export const techdocsPlugin = createBackendPlugin({ + pluginId: 'techdocs', + register(env) { + env.registerInit({ + deps: { + config: coreServices.config, + logger: coreServices.logger, + urlReader: coreServices.urlReader, + http: coreServices.httpRouter, + discovery: coreServices.discovery, + cache: coreServices.cache, + }, + async init({ config, logger, urlReader, http, discovery, cache }) { + const winstonLogger = loggerToWinstonLogger(logger); + // Preparers are responsible for fetching source files for documentation. + const preparers = await Preparers.fromConfig(config, { + reader: urlReader, + logger: winstonLogger, + }); + + // Docker client (conditionally) used by the generators, based on techdocs.generators config. + const dockerClient = new Docker(); + const containerRunner = new DockerContainerRunner({ dockerClient }); + + // Generators are used for generating documentation sites. + const generators = await Generators.fromConfig(config, { + logger: winstonLogger, + containerRunner, + }); + + // 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(config, { + logger: winstonLogger, + discovery: discovery, + }); + + // 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, + preparers, + generators, + publisher, + config, + discovery, + }), + ); + }, + }); + }, +}); diff --git a/yarn.lock b/yarn.lock index 78ceb0fba1..cd69bd547b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -8538,6 +8538,7 @@ __metadata: resolution: "@backstage/plugin-techdocs-backend@workspace:plugins/techdocs-backend" dependencies: "@backstage/backend-common": "workspace:^" + "@backstage/backend-plugin-api": "workspace:^" "@backstage/backend-test-utils": "workspace:^" "@backstage/catalog-client": "workspace:^" "@backstage/catalog-model": "workspace:^" @@ -22886,6 +22887,7 @@ __metadata: "@backstage/plugin-app-backend": "workspace:^" "@backstage/plugin-catalog-backend": "workspace:^" "@backstage/plugin-scaffolder-backend": "workspace:^" + "@backstage/plugin-techdocs-backend": "workspace:^" "@backstage/plugin-todo-backend": "workspace:^" languageName: unknown linkType: soft