From 178ffdd402409a308eb9222918ad75c25ec4b1fb Mon Sep 17 00:00:00 2001 From: Vincenzo Scamporlino Date: Tue, 7 May 2024 14:25:39 +0200 Subject: [PATCH 1/4] techdocs-cli-embedded-app: default techdocs.builder to local Signed-off-by: Vincenzo Scamporlino --- packages/techdocs-cli-embedded-app/src/apis.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/techdocs-cli-embedded-app/src/apis.ts b/packages/techdocs-cli-embedded-app/src/apis.ts index d48bee569d..5bb19a563d 100644 --- a/packages/techdocs-cli-embedded-app/src/apis.ts +++ b/packages/techdocs-cli-embedded-app/src/apis.ts @@ -72,7 +72,7 @@ class TechDocsDevStorageApi implements TechDocsStorageApi { } async getBuilder() { - return this.configApi.getString('techdocs.builder'); + return this.configApi.getOptionalString('techdocs.builder') || 'local'; } async getEntityDocs(_entityId: CompoundEntityRef, path: string) { From 8a18e9ef38bcfb390afebfb60c73fa764823e571 Mon Sep 17 00:00:00 2001 From: Vincenzo Scamporlino Date: Tue, 7 May 2024 14:28:02 +0200 Subject: [PATCH 2/4] techdocs: make builder optional Signed-off-by: Vincenzo Scamporlino --- plugins/techdocs-backend/config.d.ts | 2 +- .../techdocs-backend/src/service/DefaultDocsBuildStrategy.ts | 4 +++- plugins/techdocs/config.d.ts | 2 +- plugins/techdocs/src/client.ts | 2 +- plugins/techdocs/src/reader/components/TechDocsNotFound.tsx | 2 +- 5 files changed, 7 insertions(+), 5 deletions(-) diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts index 01da1e7926..9d1cd9e170 100644 --- a/plugins/techdocs-backend/config.d.ts +++ b/plugins/techdocs-backend/config.d.ts @@ -24,7 +24,7 @@ export interface Config { * Documentation building process depends on the builder attr * @visibility frontend */ - builder: 'local' | 'external'; + builder?: 'local' | 'external'; /** * Techdocs generator information diff --git a/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts index bc2c586c82..a0bd623b64 100644 --- a/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts +++ b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.ts @@ -29,6 +29,8 @@ export class DefaultDocsBuildStrategy implements DocsBuildStrategy { } async shouldBuild(_: { entity: Entity }): Promise { - return this.config.getString('techdocs.builder') === 'local'; + return [undefined, 'local'].includes( + this.config.getOptionalString('techdocs.builder'), + ); } } diff --git a/plugins/techdocs/config.d.ts b/plugins/techdocs/config.d.ts index 82ae8dd87a..0df852e490 100644 --- a/plugins/techdocs/config.d.ts +++ b/plugins/techdocs/config.d.ts @@ -24,7 +24,7 @@ export interface Config { * Documentation building process depends on the builder attr * @visibility frontend */ - builder: 'local' | 'external'; + builder?: 'local' | 'external'; /** * Allows fallback to case-sensitive triplets in case of migration issues. diff --git a/plugins/techdocs/src/client.ts b/plugins/techdocs/src/client.ts index ae81ecdaaa..0f11eb4068 100644 --- a/plugins/techdocs/src/client.ts +++ b/plugins/techdocs/src/client.ts @@ -151,7 +151,7 @@ export class TechDocsStorageClient implements TechDocsStorageApi { } async getBuilder(): Promise { - return this.configApi.getString('techdocs.builder'); + return this.configApi.getOptionalString('techdocs.builder') || 'local'; } /** diff --git a/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx b/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx index bd2ef26b1e..858f9c5afc 100644 --- a/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx @@ -39,7 +39,7 @@ export const TechDocsNotFound = ({ errorMessage }: Props) => { }, [analyticsApi, entityRef, location]); let additionalInfo = ''; - if (techdocsBuilder !== 'local') { + if (![undefined, 'local'].includes(techdocsBuilder)) { additionalInfo = "Note that techdocs.builder is not set to 'local' in your config, which means this Backstage app will not " + "generate docs if they are not found. Make sure the project's docs are generated and published by some external " + From 5863cf7137cef4f5e28a98b9af668fea8f934bb7 Mon Sep 17 00:00:00 2001 From: Vincenzo Scamporlino Date: Tue, 7 May 2024 14:32:17 +0200 Subject: [PATCH 3/4] techdocs: builder changesets Signed-off-by: Vincenzo Scamporlino --- .changeset/metal-years-rhyme.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/metal-years-rhyme.md diff --git a/.changeset/metal-years-rhyme.md b/.changeset/metal-years-rhyme.md new file mode 100644 index 0000000000..9c6daebdac --- /dev/null +++ b/.changeset/metal-years-rhyme.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs-backend': patch +'@backstage/plugin-techdocs': patch +--- + +The `techdocs.builder` config is now optional and it will default to `local`. From fcee1ce391f6e21c86602ee24ff1da237a9a133d Mon Sep 17 00:00:00 2001 From: Vincenzo Scamporlino Date: Tue, 7 May 2024 15:04:54 +0200 Subject: [PATCH 4/4] techdocs-backend: fix build strategy tests Signed-off-by: Vincenzo Scamporlino --- .../service/DefaultDocsBuildStrategy.test.ts | 46 ++++++++++--------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts index 7868135b08..714a3736a9 100644 --- a/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts +++ b/plugins/techdocs-backend/src/service/DefaultDocsBuildStrategy.test.ts @@ -17,12 +17,6 @@ import { DefaultDocsBuildStrategy } from './DefaultDocsBuildStrategy'; import { ConfigReader } from '@backstage/config'; -const MockedConfigReader = ConfigReader as jest.MockedClass< - typeof ConfigReader ->; - -jest.mock('@backstage/config'); - describe('DefaultDocsBuildStrategy', () => { const entity = { apiVersion: 'backstage.io/v1alpha1', @@ -33,32 +27,40 @@ describe('DefaultDocsBuildStrategy', () => { }, }; - const config = new ConfigReader({}); - - beforeEach(() => { - jest.resetAllMocks(); - }); - describe('shouldBuild', () => { - it('should return true when techdocs.build is set to local', async () => { - const defaultDocsBuildStrategy = - DefaultDocsBuildStrategy.fromConfig(config); - - MockedConfigReader.prototype.getString.mockReturnValue('local'); + it('should return true when techdocs.builder is set to local', async () => { + const defaultDocsBuildStrategy = DefaultDocsBuildStrategy.fromConfig( + new ConfigReader({ + techdocs: { + builder: 'local', + }, + }), + ); const result = await defaultDocsBuildStrategy.shouldBuild({ entity }); expect(result).toBe(true); }); - it('should return false when techdocs.build is set to external', async () => { - const defaultDocsBuildStrategy = - DefaultDocsBuildStrategy.fromConfig(config); - - MockedConfigReader.prototype.getString.mockReturnValue('external'); + it('should return true when techdocs.builder is not set', async () => { + const defaultDocsBuildStrategy = DefaultDocsBuildStrategy.fromConfig( + new ConfigReader({ techdocs: {} }), + ); const result = await defaultDocsBuildStrategy.shouldBuild({ entity }); + expect(result).toBe(true); + }); + it('should return false when techdocs.builder is set to external', async () => { + const defaultDocsBuildStrategy = DefaultDocsBuildStrategy.fromConfig( + new ConfigReader({ + techdocs: { + builder: 'external', + }, + }), + ); + + const result = await defaultDocsBuildStrategy.shouldBuild({ entity }); expect(result).toBe(false); }); });