From 92ecddbe24ab150fddb52546d20560d501f1e429 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Wed, 9 Dec 2020 20:32:41 +0100 Subject: [PATCH] techdocs-common: Unify response type of Local and googleGcs publisher --- docs/features/techdocs/architecture.md | 12 ++++++------ .../src/stages/publish/googleStorage.test.ts | 2 +- .../src/stages/publish/googleStorage.ts | 4 ++-- packages/techdocs-common/src/stages/publish/local.ts | 7 ++----- packages/techdocs-common/src/stages/publish/types.ts | 5 ++++- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md index 87fe969d46..3969002a46 100644 --- a/docs/features/techdocs/architecture.md +++ b/docs/features/techdocs/architecture.md @@ -50,8 +50,8 @@ built. We assume each entity lives in a repository somewhere (GitHub, GitLab, etc.). We recommend using a CI/CD pipeline with the repository that has a dedicated -step/job to generate docs for TechDocs. The generated static files are then stored -in a cloud storage solution of your choice. +step/job to generate docs for TechDocs. The generated static files are then +stored in a cloud storage solution of your choice. [Track progress here](https://github.com/backstage/backstage/issues/3096). Similar to how it is done in the Basic setup, the TechDocs Reader requests @@ -62,8 +62,8 @@ TechDocs Reader. We will provide instructions, scripts and/or templates (e.g. GitHub Actions) to generate docs in your CI/CD system. [Track progress here.](https://github.com/backstage/backstage/issues/3400) You -will be able to use `techdocs-cli` to generate docs and publish the generated docs -site files to your cloud storage system. +will be able to use `techdocs-cli` to generate docs and publish the generated +docs site files to your cloud storage system. Note about caching: We have noticed internally that some storage providers can be quite slow, which is why we are recommending a cache that sits between the @@ -120,8 +120,8 @@ docs site in real-time?** A: Generating the content from Markdown on the fly is not optimal (although that is how the basic out-of-the-box setup is implemented). Storage solutions act as a cache for the generated static content. TechDocs is also currently built on -MkDocs which does not allow us to generate docs per-page, so we would have to build -all docs for a entity on every request. +MkDocs which does not allow us to generate docs per-page, so we would have to +build all docs for a entity on every request. # Future work diff --git a/packages/techdocs-common/src/stages/publish/googleStorage.test.ts b/packages/techdocs-common/src/stages/publish/googleStorage.test.ts index a61dcc2767..6ab208ad03 100644 --- a/packages/techdocs-common/src/stages/publish/googleStorage.test.ts +++ b/packages/techdocs-common/src/stages/publish/googleStorage.test.ts @@ -75,6 +75,6 @@ describe('GoogleGCSPublish', () => { const entity = createMockEntity(); return expect( publisher.publish({ entity, directory: '/path/to/generatedDirectory' }), - ).resolves.toStrictEqual({}); + ).resolves.toBeUndefined(); }); }); diff --git a/packages/techdocs-common/src/stages/publish/googleStorage.ts b/packages/techdocs-common/src/stages/publish/googleStorage.ts index d6868c1103..342b0a2687 100644 --- a/packages/techdocs-common/src/stages/publish/googleStorage.ts +++ b/packages/techdocs-common/src/stages/publish/googleStorage.ts @@ -93,7 +93,7 @@ export class GoogleGCSPublish implements PublisherBase { * Upload all the files from the generated `directory` to the GCS bucket. * Directory structure used in the bucket is - entityNamespace/entityKind/entityName/index.html */ - publish({ entity, directory }: PublishRequest): Promise<{}> { + publish({ entity, directory }: PublishRequest): Promise { return new Promise((resolve, reject) => { // Path of all files to upload, relative to the root of the source directory // e.g. ['index.html', 'sub-page/index.html', 'assets/images/favicon.png'] @@ -140,7 +140,7 @@ export class GoogleGCSPublish implements PublisherBase { this.logger.info( `Successfully uploaded all the generated files for Entity ${entityRootDir}. Total number of files: ${allFilesToUpload.length}`, ); - resolve({}); + resolve(undefined); }); }); } diff --git a/packages/techdocs-common/src/stages/publish/local.ts b/packages/techdocs-common/src/stages/publish/local.ts index 7bb670f2d4..bc24867f50 100644 --- a/packages/techdocs-common/src/stages/publish/local.ts +++ b/packages/techdocs-common/src/stages/publish/local.ts @@ -23,10 +23,7 @@ import { PluginEndpointDiscovery, } from '@backstage/backend-common'; import { Config } from '@backstage/config'; -import { PublisherBase, PublishRequest } from './types'; - -/* `remoteUrl` is the URL which serves files from the local publisher's static directory. */ -export type LocalPublishReturn = Promise<{ remoteUrl: string }>; +import { PublisherBase, PublishRequest, PublishResponse } from './types'; const staticDocsDir = resolvePackagePath( '@backstage/plugin-techdocs-backend', @@ -52,7 +49,7 @@ export class LocalPublish implements PublisherBase { this.discovery = discovery; } - publish({ entity, directory }: PublishRequest): LocalPublishReturn { + publish({ entity, directory }: PublishRequest): Promise { const entityNamespace = entity.metadata.namespace ?? 'default'; const publishDir = resolvePackagePath( diff --git a/packages/techdocs-common/src/stages/publish/types.ts b/packages/techdocs-common/src/stages/publish/types.ts index 6722f6c221..9bfd8cb334 100644 --- a/packages/techdocs-common/src/stages/publish/types.ts +++ b/packages/techdocs-common/src/stages/publish/types.ts @@ -27,7 +27,10 @@ export type PublishRequest = { directory: string; }; -export type PublishResponse = {}; +/* `remoteUrl` is the URL which serves files from the local publisher's static directory. */ +export type PublishResponse = { + remoteUrl?: string; +} | void; /** * Base class for a TechDocs publisher (e.g. Local, Google GCS Bucket, AWS S3, etc.)