From 4bc89c555a68fd8c0827c22217b25e64f1a736fe Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Thu, 28 Jan 2021 14:54:48 +0100 Subject: [PATCH 1/5] TechDocs: Dir preparer should also use URL Reader --- app-config.yaml | 2 +- .../techdocs-common/src/stages/prepare/dir.ts | 18 +++++++++++------- .../src/stages/prepare/preparers.ts | 13 +++++++++---- 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/app-config.yaml b/app-config.yaml index c150ef5902..010c9b9710 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -208,7 +208,7 @@ catalog: # Backstage example components - type: file target: ../catalog-model/examples/all-components.yaml - # Example component for github-actions + # Example component for github-actions and TechDocs - type: file target: ../../plugins/github-actions/examples/sample.yaml # Example component for TechDocs diff --git a/packages/techdocs-common/src/stages/prepare/dir.ts b/packages/techdocs-common/src/stages/prepare/dir.ts index 537f670edc..ab277fda9a 100644 --- a/packages/techdocs-common/src/stages/prepare/dir.ts +++ b/packages/techdocs-common/src/stages/prepare/dir.ts @@ -18,17 +18,19 @@ import { Entity } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; import path from 'path'; import { parseReferenceAnnotation, checkoutGitRepository } from '../../helpers'; -import { InputError } from '@backstage/backend-common'; +import { UrlReader, InputError } from '@backstage/backend-common'; import parseGitUrl from 'git-url-parse'; import { Logger } from 'winston'; export class DirectoryPreparer implements PreparerBase { - private readonly config: Config; - private readonly logger: Logger; - - constructor(config: Config, logger: Logger) { + constructor( + private readonly config: Config, + private readonly logger: Logger, + private readonly reader: UrlReader, + ) { this.config = config; this.logger = logger; + this.reader = reader; } private async resolveManagedByLocationToDir(entity: Entity) { @@ -41,9 +43,12 @@ export class DirectoryPreparer implements PreparerBase { `Building docs for entity with type 'dir' and managed-by-location '${type}'`, ); switch (type) { + case 'url': { + const response = await this.reader.readTree(target); + return await response.dir(); + } case 'github': case 'gitlab': - case 'url': case 'azure/api': { const parsedGitLocation = parseGitUrl(target); const repoLocation = await checkoutGitRepository( @@ -56,7 +61,6 @@ export class DirectoryPreparer implements PreparerBase { path.join(repoLocation, parsedGitLocation.filepath), ); } - case 'file': return path.dirname(target); default: diff --git a/packages/techdocs-common/src/stages/prepare/preparers.ts b/packages/techdocs-common/src/stages/prepare/preparers.ts index 4625d7b0e4..de825d5d41 100644 --- a/packages/techdocs-common/src/stages/prepare/preparers.ts +++ b/packages/techdocs-common/src/stages/prepare/preparers.ts @@ -35,17 +35,22 @@ export class Preparers implements PreparerBuilder { ): Promise { const preparers = new Preparers(); - const directoryPreparer = new DirectoryPreparer(config, logger); + const urlPreparer = new UrlPreparer(reader, logger); + preparers.register('url', urlPreparer); + + /** + * Dir preparer is a syntactic sugar for users to define techdocs-ref annotation. + * When using dir preparer, the docs will be fetched using URL Reader. + */ + const directoryPreparer = new DirectoryPreparer(config, logger, reader); preparers.register('dir', directoryPreparer); + // Common git preparers will be deprecated soon. const commonGitPreparer = new CommonGitPreparer(config, logger); preparers.register('github', commonGitPreparer); preparers.register('gitlab', commonGitPreparer); preparers.register('azure/api', commonGitPreparer); - const urlPreparer = new UrlPreparer(reader, logger); - preparers.register('url', urlPreparer); - return preparers; } From f680c6cd219b72f4771bb96578825fe07a9d395b Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Thu, 28 Jan 2021 15:12:41 +0100 Subject: [PATCH 2/5] TechDocs: Update docs to use URL Reader over dir preparer --- docs/features/techdocs/creating-and-publishing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 187fe97aed..b32bda1e15 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -66,7 +66,9 @@ Update your component's entity description by adding the following lines to its ```yaml metadata: annotations: - backstage.io/techdocs-ref: dir:./ + backstage.io/techdocs-ref: url:https://github.com/org/repo + # Or + # backstage.io/techdocs-ref: url:https://github.com/org/repo/tree/branchName/subFolder ``` Create a `/docs` folder in the root of the project with at least an `index.md` From f0320190d795e6a50ae1644349f995dbca7ae4b0 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Thu, 28 Jan 2021 15:13:36 +0100 Subject: [PATCH 3/5] TechDocs: Add changeset for dir preparer improvement --- .changeset/techdocs-chilly-steaks-brush.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/techdocs-chilly-steaks-brush.md diff --git a/.changeset/techdocs-chilly-steaks-brush.md b/.changeset/techdocs-chilly-steaks-brush.md new file mode 100644 index 0000000000..7fd4763c63 --- /dev/null +++ b/.changeset/techdocs-chilly-steaks-brush.md @@ -0,0 +1,5 @@ +--- +'@backstage/techdocs-common': patch +--- + +dir preparer will use URL Reader in its implementation. From 03a2d95c71da258fffd07a2b3121aa59583d828c Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Thu, 28 Jan 2021 15:27:39 +0100 Subject: [PATCH 4/5] TechDocs: Update tests with mock url reader --- .../src/stages/prepare/dir.test.ts | 24 +++++++++++++++---- .../src/service/standaloneServer.ts | 11 ++++++++- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/packages/techdocs-common/src/stages/prepare/dir.test.ts b/packages/techdocs-common/src/stages/prepare/dir.test.ts index d082b1367b..630608e817 100644 --- a/packages/techdocs-common/src/stages/prepare/dir.test.ts +++ b/packages/techdocs-common/src/stages/prepare/dir.test.ts @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -import { getVoidLogger } from '@backstage/backend-common'; +import { getVoidLogger, UrlReader } from '@backstage/backend-common'; import { ConfigReader } from '@backstage/config'; import { DirectoryPreparer } from './dir'; import { checkoutGitRepository } from '../../helpers'; @@ -46,10 +46,18 @@ const createMockEntity = (annotations: {}) => { }; const mockConfig = new ConfigReader({}); +const mockUrlReader: jest.Mocked = { + read: jest.fn(), + readTree: jest.fn(), +}; describe('directory preparer', () => { it('should merge managed-by-location and techdocs-ref when techdocs-ref is relative', async () => { - const directoryPreparer = new DirectoryPreparer(mockConfig, logger); + const directoryPreparer = new DirectoryPreparer( + mockConfig, + logger, + mockUrlReader, + ); const mockEntity = createMockEntity({ 'backstage.io/managed-by-location': @@ -63,7 +71,11 @@ describe('directory preparer', () => { }); it('should merge managed-by-location and techdocs-ref when techdocs-ref is absolute', async () => { - const directoryPreparer = new DirectoryPreparer(mockConfig, logger); + const directoryPreparer = new DirectoryPreparer( + mockConfig, + logger, + mockUrlReader, + ); const mockEntity = createMockEntity({ 'backstage.io/managed-by-location': @@ -77,7 +89,11 @@ describe('directory preparer', () => { }); it('should merge managed-by-location and techdocs-ref when managed-by-location is a git repository', async () => { - const directoryPreparer = new DirectoryPreparer(mockConfig, logger); + const directoryPreparer = new DirectoryPreparer( + mockConfig, + logger, + mockUrlReader, + ); const mockEntity = createMockEntity({ 'backstage.io/managed-by-location': diff --git a/plugins/techdocs-backend/src/service/standaloneServer.ts b/plugins/techdocs-backend/src/service/standaloneServer.ts index 721c10a1ec..d91e2f08a2 100644 --- a/plugins/techdocs-backend/src/service/standaloneServer.ts +++ b/plugins/techdocs-backend/src/service/standaloneServer.ts @@ -17,6 +17,7 @@ import { createServiceBuilder, SingleHostDiscovery, + UrlReader, } from '@backstage/backend-common'; import { Server } from 'http'; import { Logger } from 'winston'; @@ -49,10 +50,18 @@ export async function startStandaloneServer( }, }); const discovery = SingleHostDiscovery.fromConfig(config); + const mockUrlReader: jest.Mocked = { + read: jest.fn(), + readTree: jest.fn(), + }; logger.debug('Creating application...'); const preparers = new Preparers(); - const directoryPreparer = new DirectoryPreparer(config, logger); + const directoryPreparer = new DirectoryPreparer( + config, + logger, + mockUrlReader, + ); preparers.register('dir', directoryPreparer); const generators = new Generators(); From 4f32647f00e79d6a3673e80208d47e063689bcc3 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Thu, 28 Jan 2021 16:01:10 +0100 Subject: [PATCH 5/5] TechDocs: docs - Add reference link to techdocs-ref annotation --- docs/features/techdocs/creating-and-publishing.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index b32bda1e15..c15dc1fe69 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -71,6 +71,11 @@ metadata: # backstage.io/techdocs-ref: url:https://github.com/org/repo/tree/branchName/subFolder ``` +The +[`backstage.io/techdocs-ref` annotation](../software-catalog/well-known-annotations.md#backstageiotechdocs-ref) +is used by TechDocs to download the documentation source files for generating an +Entity's TechDocs site. + Create a `/docs` folder in the root of the project with at least an `index.md` file. _(If you add more markdown files, make sure to update the nav in the mkdocs.yml file to get a proper navigation for your documentation.)_