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

refactor(techdocs-common): apply review suggestions

Browse Source 
Signed-off-by: Camila Belo <camilaibs@gmail.com>
This commit is contained in:
Camila Belo
2022-02-24 09:08:23 +01:00
parent bda799308c
commit c13f768521
14 changed files with 64 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/techdocs-common/src/helpers.ts
+4 -4
View File
@@ -39,7 +39,7 @@ export type ParsedLocationAnnotation = {
* Returns a parset locations annotation
* @public
* @param annotationName - The name of the annotation in the entity metadata
* @param entity - A Tech Docs entity instance
* @param entity - A TechDocs entity instance
*/
export const parseReferenceAnnotation = (
annotationName: string,
@@ -112,9 +112,9 @@ export const transformDirLocation = (
};
/**
* Returns a entity reference based on the Tech Docs annotation type
* Returns a entity reference based on the TechDocs annotation type
* @public
* @param entity - A Tech Docs instance
* @param entity - A TechDocs instance
* @param scmIntegration - An implementation for SCM integration API
*/
export const getLocationForEntity = (
@@ -140,7 +140,7 @@ export const getLocationForEntity = (
* Returns a preparer response {@link PreparerResponse}
* @public
* @param reader - Read a tree of files from a repository
* @param entity - A Tech Docs entity instance
* @param entity - A TechDocs entity instance
* @param opts - Options for configuring the reader, e.g. logger, etag, etc.
*/
export const getDocFilesFromRepository = async (
packages/techdocs-common/src/stages/generate/generators.ts
+4 -4
View File
@@ -34,9 +34,9 @@ export class Generators implements GeneratorBuilder {
private generatorMap = new Map<SupportedGeneratorKey, GeneratorBase>();
/**
* Returns a generators instance containing a generator for Tech Docs
* Returns a generators instance containing a generator for TechDocs
* @param config - A Backstage configuration
* @param options - Options to configure the Tech Docs generator
* @param options - Options to configure the TechDocs generator
*/
static async fromConfig(
config: Config,
@@ -60,8 +60,8 @@ export class Generators implements GeneratorBuilder {
}
/**
* Returns the generator for a given Tech Docs entity
* @param entity - A Tech Docs entity instance
* Returns the generator for a given TechDocs entity
* @param entity - A TechDocs entity instance
*/
get(entity: Entity): GeneratorBase {
const generatorKey = getGeneratorKey(entity);
packages/techdocs-common/src/stages/generate/index.ts
+1 -1
View File
@@ -17,8 +17,8 @@ export { TechdocsGenerator } from './techdocs';
export { Generators } from './generators';
export type {
GeneratorBase,
GeneratorOptions,
GeneratorBuilder,
GeneratorFactory,
GeneratorRunOptions,
SupportedGeneratorKey,
} from './types';
packages/techdocs-common/src/stages/generate/techdocs.ts
+3 -3
View File
@@ -34,11 +34,11 @@ import {
import {
GeneratorBase,
GeneratorConfig,
GeneratorOptions,
GeneratorRunInType,
GeneratorRunOptions,
} from './types';
import { ForwardedError } from '@backstage/errors';
import { GeneratorFactory } from './types';
/**
* Generates documentation files
@@ -56,11 +56,11 @@ export class TechdocsGenerator implements GeneratorBase {
private readonly scmIntegrations: ScmIntegrationRegistry;
/**
* Returns a instance of Tech Docs generator
* Returns a instance of TechDocs generator
* @param config - A Backstage configuration
* @param options - Options to configure the generator
*/
static fromConfig(config: Config, options: GeneratorFactory) {
static fromConfig(config: Config, options: GeneratorOptions) {
const { containerRunner, logger } = options;
const scmIntegrations = ScmIntegrations.fromConfig(config);
return new TechdocsGenerator({
packages/techdocs-common/src/stages/generate/types.ts
+1 -1
View File
@@ -27,7 +27,7 @@ export type GeneratorRunInType = 'docker' | 'local';
* Options for building generators
* @public
*/
export type GeneratorFactory = {
export type GeneratorOptions = {
containerRunner: ContainerRunner;
logger: Logger;
};
packages/techdocs-common/src/stages/prepare/dir.ts
+4 -4
View File
@@ -26,9 +26,9 @@ import { Logger } from 'winston';
import { parseReferenceAnnotation, transformDirLocation } from '../../helpers';
import {
PreparerBase,
PreparerConfig,
PreparerOptions,
PreparerResponse,
DirectoryFactory,
} from './types';
/**
@@ -48,13 +48,13 @@ export class DirectoryPreparer implements PreparerBase {
/**
* Returns a directory preparer instance
* @param config - A backstage config
* @param options - A directory preparer options containing the URL reader
* @param options - A directory preparer options containing a logger and reader
*/
static fromConfig(
config: Config,
options: DirectoryFactory,
{ logger, reader }: PreparerConfig,
): DirectoryPreparer {
return new DirectoryPreparer(config, null, options.reader);
return new DirectoryPreparer(config, logger, reader);
}
/** {@inheritDoc PreparerBase.prepare} */
packages/techdocs-common/src/stages/prepare/index.ts
+1 -3
View File
@@ -19,11 +19,9 @@ export { Preparers } from './preparers';
export type {
PreparerBase,
PreparerBuilder,
PreparerFactory,
PreparerConfig,
PreparerOptions,
PreparerResponse,
DirectoryFactory,
UrlFactory,
RemoteProtocol,
ETag,
} from './types';
packages/techdocs-common/src/stages/prepare/preparers.ts
+14 -10
View File
@@ -21,26 +21,26 @@ import { UrlPreparer } from './url';
import {
PreparerBase,
PreparerBuilder,
PreparerFactory,
PreparerConfig,
RemoteProtocol,
} from './types';
/**
* Collection of docs preparers
* Collection of docs preparers (dir and url)
* @public
*/
export class Preparers implements PreparerBuilder {
private preparerMap = new Map<RemoteProtocol, PreparerBase>();
/**
* Returns a generators instance containing a generator for Tech Docs
* Returns a generators instance containing a generator for TechDocs
* @public
* @param config - A Backstage configuration
* @param options - Options to configure the URL preparer
* @param backstageConfig - A Backstage configuration
* @param preparerConfig - Options to configure preparers
*/
static async fromConfig(
config: Config,
{ logger, reader }: PreparerFactory,
backstageConfig: Config,
{ logger, reader }: PreparerConfig,
): Promise<PreparerBuilder> {
const preparers = new Preparers();
@@ -51,7 +51,11 @@ export class Preparers implements PreparerBuilder {
* 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);
const directoryPreparer = new DirectoryPreparer(
backstageConfig,
logger,
reader,
);
preparers.register('dir', directoryPreparer);
return preparers;
@@ -67,8 +71,8 @@ export class Preparers implements PreparerBuilder {
}
/**
* Returns the preparer for a given Tech Docs entity
* @param entity - A Tech Docs entity instance
* Returns the preparer for a given TechDocs entity
* @param entity - A TechDocs entity instance
* @returns
*/
get(entity: Entity): PreparerBase {
packages/techdocs-common/src/stages/prepare/types.ts
+11 -25
View File
@@ -18,35 +18,21 @@ import type { Entity } from '@backstage/catalog-model';
import { UrlReader } from '@backstage/backend-common';
import { Logger } from 'winston';
/**
* Options for building preparers
* @public
*/
export type PreparerFactory = {
logger: Logger;
reader: UrlReader;
};
/**
* Options to configure a directory preparer.
* @public
*/
export type DirectoryFactory = {
reader: UrlReader;
};
/**
* Options to configure a url preparer.
* @public
*/
export type UrlFactory = PreparerFactory;
/**
* A unique identifier of the tree blob, usually the commit SHA or etag from the target.
* @public
*/
export type ETag = string;
/**
* Options for building preparers
* @public
*/
export type PreparerConfig = {
logger: Logger;
reader: UrlReader;
};
/**
* Options for configuring the content preparation process.
* @public
@@ -78,7 +64,7 @@ export type PreparerResponse = {
};
/**
* Definition of a Tech Docs preparer
* Definition of a TechDocs preparer
* @public
*/
export type PreparerBase = {
@@ -95,7 +81,7 @@ export type PreparerBase = {
};
/**
* Definition for a Tech Docs preparer builder
* Definition for a TechDocs preparer builder
* @public
*/
export type PreparerBuilder = {
packages/techdocs-common/src/stages/prepare/url.ts
+10 -6
View File
@@ -19,7 +19,12 @@ import { UrlReader } from '@backstage/backend-common';
import { Entity } from '@backstage/catalog-model';
import { Logger } from 'winston';
import { getDocFilesFromRepository } from '../../helpers';
import { PreparerBase, PreparerResponse, UrlFactory } from './types';
import {
PreparerBase,
PreparerConfig,
PreparerOptions,
PreparerResponse,
} from './types';
/**
* Preparer used to retrieve documentation files from a remote repository
@@ -37,17 +42,16 @@ export class UrlPreparer implements PreparerBase {
/**
* Returns a directory preparer instance
* @param config - A backstage config
* @param options - A directory preparer options containing the URL reader
* @param config - A URL preparer config containing the a logger and reader
*/
static fromConfig(options: UrlFactory): UrlPreparer {
return new UrlPreparer(options.reader, options.logger);
static fromConfig({ reader, logger }: PreparerConfig): UrlPreparer {
return new UrlPreparer(reader, logger);
}
/** {@inheritDoc PreparerBase.prepare} */
async prepare(
entity: Entity,
options?: { etag?: string },
options?: PreparerOptions,
): Promise<PreparerResponse> {
try {
return await getDocFilesFromRepository(this.reader, entity, {
packages/techdocs-common/src/stages/publish/publish.ts
+1 -1
View File
@@ -29,7 +29,7 @@ import { PublisherFactory, PublisherBase, PublisherType } from './types';
*/
export class Publisher {
/**
* Returns a instance of Tech Docs publisher
* Returns a instance of TechDocs publisher
* @param config - A Backstage configuration
* @param options - Options for configuring the publisher factory
*/
packages/techdocs-common/src/stages/publish/types.ts
+1 -1
View File
@@ -89,7 +89,7 @@ export type TechDocsMetadata = {
};
/**
* Tech Docs entity triplet migration request
* TechDocs entity triplet migration request
* @public
*/
export type MigrateRequest = {
packages/techdocs-common/src/techdocsTypes.ts
+1 -1
View File
@@ -17,7 +17,7 @@
import { IndexableDocument } from '@backstage/search-common';
/**
* Tech Docs indexable document interface
* TechDocs indexable document interface
* @public
*/
export interface TechDocsDocument extends IndexableDocument {