Merge branch 'backstage:master' into master
This commit is contained in:
Waldir Montoya
@@ -61,7 +61,7 @@ class DefaultFooService implements FooService {
|
||||
}
|
||||
}
|
||||
|
||||
export const fooFactory = createServiceFactory({
|
||||
export const fooServiceFactory = createServiceFactory({
|
||||
service: fooServiceRef,
|
||||
deps: { bar: barServiceRef },
|
||||
factory({ bar }) {
|
||||
@@ -75,7 +75,7 @@ To create a service factory we need to provide a reference to the `service` for
|
||||
If you need the creation of the service instance to be asynchronous, you can make the `factory` function async. For example:
|
||||
|
||||
```ts
|
||||
export const fooFactory = createServiceFactory({
|
||||
export const fooServiceFactory = createServiceFactory({
|
||||
service: fooServiceRef,
|
||||
deps: {},
|
||||
async factory() {
|
||||
@@ -94,18 +94,18 @@ To install a service factory in a backend instance, we pass it in through the `s
|
||||
|
||||
```ts
|
||||
const backend = createBackend({
|
||||
services: [fooFactory()],
|
||||
services: [fooServiceFactory()],
|
||||
});
|
||||
```
|
||||
|
||||
Note that we call `fooFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. This is done to always allow for options to be added to the service factory in the future, without breaking existing code. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. For example:
|
||||
Note that we call `fooServiceFactory` to create the service factory instance. This is because `createServiceFactory` always returns a factory function that creates the actual service factory. This is done to always allow for options to be added to the service factory in the future, without breaking existing code. To add options to your service factory, you wrap the object passed to `createServiceFactory` in a callback that accepts the desired options. For example:
|
||||
|
||||
```ts
|
||||
export interface FooFactoryOptions {
|
||||
mode: 'eager' | 'lazy';
|
||||
}
|
||||
|
||||
export const fooFactory = createServiceFactory(
|
||||
export const fooServiceFactory = createServiceFactory(
|
||||
(options?: FooFactoryOptions) => ({
|
||||
service: fooServiceRef,
|
||||
deps: { bar: barServiceRef },
|
||||
@@ -120,7 +120,7 @@ This lets us use the options to customize the factory implementation in any way
|
||||
|
||||
```ts
|
||||
const backend = createBackend({
|
||||
services: [fooFactory({ mode: 'eager' })],
|
||||
services: [fooServiceFactory({ mode: 'eager' })],
|
||||
});
|
||||
```
|
||||
|
||||
@@ -164,7 +164,7 @@ Plugin scoped services have access to a plugin metadata service, which is a spec
|
||||
The plugin metadata service is the base for all plugin specific customizations for services. For example, the default implementation of the plugin scoped logger service uses the plugin metadata service to attach the plugin ID as a field in all log messages:
|
||||
|
||||
```ts
|
||||
export const loggerFactory = createServiceFactory({
|
||||
export const loggerServiceFactory = createServiceFactory({
|
||||
service: coreServices.logger,
|
||||
deps: {
|
||||
rootLogger: coreServices.rootLogger,
|
||||
@@ -183,7 +183,7 @@ Some services may benefit from having a context that is shared across all instan
|
||||
The root context is defined as part of the service factory by passing the `createRootContext` option:
|
||||
|
||||
```ts
|
||||
export const fooFactory = createServiceFactory({
|
||||
export const fooServiceFactory = createServiceFactory({
|
||||
service: fooServiceRef,
|
||||
deps: { rootLogger: coreServices.rootLogger, bar: barServiceRef },
|
||||
createRootContext({ rootLogger }) {
|
||||
|
||||
@@ -66,12 +66,12 @@ export const catalogProcessingExtensionPoint = createExtensionPoint<CatalogProce
|
||||
|
||||
### Services
|
||||
|
||||
| Description | Pattern | Examples |
|
||||
| ----------- | ------------------- | -------------------------------------------------- |
|
||||
| Interface | `<Name>Service` | `LoggerService`, `DatabaseService` |
|
||||
| Reference | `<name>ServiceRef` | `loggerServiceRef`, `databaseServiceRef` |
|
||||
| ID | `<pluginId>.<name>` | `'core.rootHttpRouter'`, `'catalog.catalogClient'` |
|
||||
| Factory | `<name>Factory` | `loggerFactory`, `databaseFactory` |
|
||||
| Description | Pattern | Examples |
|
||||
| ----------- | ---------------------- | -------------------------------------------------- |
|
||||
| Interface | `<Name>Service` | `LoggerService`, `DatabaseService` |
|
||||
| Reference | `<name>ServiceRef` | `loggerServiceRef`, `databaseServiceRef` |
|
||||
| ID | `<pluginId>.<name>` | `'core.rootHttpRouter'`, `'catalog.catalogClient'` |
|
||||
| Factory | `<name>ServiceFactory` | `loggerServiceFactory`, `databaseServiceFactory` |
|
||||
|
||||
Example:
|
||||
|
||||
@@ -85,7 +85,7 @@ export const catalogClientServiceRef = createServiceRef<CatalogClientService>({
|
||||
...
|
||||
})
|
||||
|
||||
export const catalogClientFactory = createServiceFactory({
|
||||
export const catalogClientServiceFactory = createServiceFactory({
|
||||
service: catalogClientServiceRef,
|
||||
...
|
||||
})
|
||||
|
||||
@@ -61,11 +61,11 @@ All of these services can be replaced with your own implementations if you need
|
||||
For example, let's say we want to customize the core configuration service to enable remote configuration loading. That would look something like this:
|
||||
|
||||
```ts
|
||||
import { configFactory } from '@backstage/backend-app-api';
|
||||
import { configServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
configFactory({
|
||||
configServiceFactory({
|
||||
remote: { reloadIntervalSeconds: 60 },
|
||||
}),
|
||||
],
|
||||
@@ -160,11 +160,11 @@ A shared environment is defined using `createSharedEnvironment`. In this example
|
||||
```ts
|
||||
// packages/backend-env/src/index.ts
|
||||
import { createSharedEnvironment } from '@backstage/backend-plugin-api';
|
||||
import { customDiscoveryFactory } from './customDiscoveryFactory';
|
||||
import { customDiscoveryServiceFactory } from './customDiscoveryServiceFactory';
|
||||
|
||||
export const env = createSharedEnvironment({
|
||||
services: [
|
||||
customDiscoveryFactory(), // custom DiscoveryService implementation
|
||||
customDiscoveryServiceFactory(), // custom DiscoveryService implementation
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
@@ -59,11 +59,11 @@ There's additional configuration that you can optionally pass to setup the `http
|
||||
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
|
||||
|
||||
```ts
|
||||
import { httpRouterFactory } from '@backstage/backend-app-api';
|
||||
import { httpRouterServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
httpRouterFactory({
|
||||
httpRouterServiceFactory({
|
||||
getPath: (pluginId: string) => `/plugins/${pluginId}`,
|
||||
}),
|
||||
],
|
||||
@@ -116,11 +116,11 @@ There's additional options that you can pass to configure the root HTTP Router s
|
||||
You can configure the root HTTP Router service by passing the options to the `createBackend` function.
|
||||
|
||||
```ts
|
||||
import { rootHttpRouterFactory } from '@backstage/backend-app-api';
|
||||
import { rootHttpRouterServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
rootHttpRouterFactory({
|
||||
rootHttpRouterServiceFactory({
|
||||
configure: ({ app, middleware, routes, config, logger, lifecycle }) => {
|
||||
// the built in middleware is provided through an option in the configure function
|
||||
app.use(middleware.helmet());
|
||||
@@ -183,11 +183,11 @@ There's additional configuration that you can optionally pass to setup the `conf
|
||||
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
|
||||
|
||||
```ts
|
||||
import { configFactory } from '@backstage/backend-app-api';
|
||||
import { configServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
configFactory({
|
||||
configServiceFactory({
|
||||
argv: [
|
||||
'--config',
|
||||
'/backstage/app-config.development.yaml',
|
||||
@@ -438,11 +438,11 @@ There's additional configuration that you can optionally pass to setup the `iden
|
||||
You can configure these additional options by adding an override for the core service when calling `createBackend` like follows:
|
||||
|
||||
```ts
|
||||
import { identityFactory } from '@backstage/backend-app-api';
|
||||
import { identityServiceFactory } from '@backstage/backend-app-api';
|
||||
|
||||
const backend = createBackend({
|
||||
services: [
|
||||
identityFactory({
|
||||
identityServiceFactory({
|
||||
issuer: 'backstage',
|
||||
algorithms: ['ES256', 'RS256'],
|
||||
}),
|
||||
|
||||
@@ -125,6 +125,7 @@ discover available Addons, we've compiled a list of them here:
|
||||
| [`<ExpandableNavigation />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. |
|
||||
| [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. |
|
||||
| [`<TextSize />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. |
|
||||
| [`<LightBox />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. |
|
||||
|
||||
Got an Addon to contribute? Feel free to add a row above!
|
||||
|
||||
|
||||
@@ -262,12 +262,12 @@ You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
|
||||
pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g.
|
||||
apt).
|
||||
|
||||
You can do so by including the following lines in the last step of your
|
||||
You can do so by including the following lines right above `USER node` of your
|
||||
`Dockerfile`:
|
||||
|
||||
```Dockerfile
|
||||
RUN apt-get update && apt-get install -y python3 python3-pip
|
||||
RUN pip3 install mkdocs-techdocs-core==1.0.1
|
||||
RUN pip3 install mkdocs-techdocs-core==1.1.7
|
||||
```
|
||||
|
||||
Please be aware that the version requirement could change, you need to check our
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user