Merge pull request #19377 from backstage/freben/docs3

document the explore and techdocs collators too
2023-08-15 17:11:30 +02:00
parent cfa778a5dc 2931c399f6
commit 45224b9fd4
4 changed files with 55 additions and 48 deletions
@@ -2,14 +2,21 @@

 > DISCLAIMER: The new backend system is in alpha, and so are the search backend module support for the new backend system. We don't recommend you to migrate your backend installations to the new system yet. But if you want to experiment, you can find getting started guides below.

-This package exports explore backend modules responsible for extending search.
+This package exports a module that extends the search backend to also indexing the tools exposed by the [`explore` service](https://github.com/backstage/backstage/tree/master/plugins/explore-backend).

-## Example
+## Installation

-### Use default schedule
+Add the module package as a dependency:
+
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-search-backend-module-explore
+```
+
+Add the collator to your backend instance, along with the search plugin itself:

 ```tsx
-// packages/backend-next/src/index.ts
+// packages/backend/src/index.ts
 import { createBackend } from '@backstage/backend-defaults';
 import { searchPlugin } from '@backstage/plugin-search-backend/alpha';
 import { searchModuleExploreCollator } from '@backstage/plugin-search-backend-module-explore/alpha';
@@ -20,29 +27,11 @@ backend.add(searchModuleExploreCollator());
 backend.start();
 ```

-### Use custom schedule
+You may also want to add configuration parameters to your app-config, for example for controlling the scheduled indexing interval. These parameters should be placed under the `search.collators.explore` key. See [the config definition file](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-explore/config.d.ts) for more details.

-```tsx
-// packages/backend-next/src/index.ts
-import { createBackend } from '@backstage/backend-defaults';
-import { searchPlugin } from '@backstage/plugin-search-backend/alpha';
-import { searchModuleExploreCollator } from '@backstage/plugin-search-backend-module-explore/alpha';
+## Using Auth Middleware

-const schedule = {
-  frequency: { minutes: 10 },
-  timeout: { minutes: 15 },
-  initialDelay: { seconds: 3 },
-};
-
-const backend = createBackend();
-backend.add(searchPlugin());
-backend.add(searchModuleExploreCollator({ schedule }));
-backend.start();
-```
-
-### Using Auth Middleware
-
-If your Backstage instance uses service-to-service authentication you can pass an optional `tokenManager` to the collator factory. This will ensure that the collator makes authenticated requests to the explore backend.
+If your Backstage instance uses service-to-service authentication, the collator will need to have access to a `tokenManager`. This is automatically injected by the collator module when using the new backend system. But if you are using the old backend system, you will want to add it manually to ensure that the collator makes authenticated requests to the explore backend.

 ```tsx
 indexBuilder.addCollator({
@@ -19,7 +19,13 @@ import { TaskScheduleDefinitionConfig } from '@backstage/backend-tasks';
 export interface Config {
  search?: {
    collators?: {
+      /**
+       * Configuration options for `@backstage/plugin-search-backend-module-explore`
+       */
      explore?: {
+        /**
+         * The schedule for how often to run the collation job.
+         */
        schedule?: TaskScheduleDefinitionConfig;
      };
    };
@@ -2,14 +2,21 @@

 > DISCLAIMER: The new backend system is in alpha, and so are the search backend module support for the new backend system. We don't recommend you to migrate your backend installations to the new system yet. But if you want to experiment, you can find getting started guides below.

-This package exports techdocs backend modules responsible for extending search.
+This package exports a module that extends the search backend to also index techdocs.

-## Example
+## Installation

-### Use default schedule
+Add the module package as a dependency:
+
+```bash
+# From your Backstage root directory
+yarn add --cwd packages/backend @backstage/plugin-search-backend-module-techdocs
+```
+
+Add the collator to your backend instance, along with the search plugin itself:

 ```tsx
-// packages/backend-next/src/index.ts
+// packages/backend/src/index.ts
 import { createBackend } from '@backstage/backend-defaults';
 import { searchPlugin } from '@backstage/plugin-search-backend/alpha';
 import { searchModuleTechDocsCollator } from '@backstage/plugin-search-backend-module-techdocs/alpha';
@@ -20,22 +27,4 @@ backend.add(searchModuleTechDocsCollator());
 backend.start();
 ```

-### Use custom schedule
-
-```tsx
-// packages/backend-next/src/index.ts
-import { createBackend } from '@backstage/backend-defaults';
-import { searchPlugin } from '@backstage/plugin-search-backend/alpha';
-import { searchModuleTechDocsCollator } from '@backstage/plugin-search-backend-module-techdocs/alpha';
-
-const schedule = {
-  frequency: { minutes: 10 },
-  timeout: { minutes: 15 },
-  initialDelay: { seconds: 3 },
-};
-
-const backend = createBackend();
-backend.add(searchPlugin());
-backend.add(searchModuleTechDocsCollator({ schedule }));
-backend.start();
-```
+You may also want to add configuration parameters to your app-config, for example for controlling the scheduled indexing interval. These parameters should be placed under the `search.collators.techdocs` key. See [the config definition file](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-techdocs/config.d.ts) for more details.
@@ -19,10 +19,33 @@ import { TaskScheduleDefinitionConfig } from '@backstage/backend-tasks';
 export interface Config {
  search?: {
    collators?: {
+      /**
+       * Configuration options for `@backstage/plugin-search-backend-module-techdocs`
+       */
      techdocs?: {
+        /**
+         * The schedule for how often to run the collation job.
+         */
        schedule?: TaskScheduleDefinitionConfig;
+        /**
+         * A templating string with placeholders, to form the final location of
+         * the entity.
+         *
+         * Defaults to `'/docs/:namespace/:kind/:name/:path'`.
+         */
        locationTemplate?: string;
+        /**
+         * An abstract value that controls the concurrency level of the
+         * collation process. Increasing this value will both increase the
+         * number of entities fetched at a time from the catalog, as well as how
+         * many things are being processed concurrently.
+         *
+         * Defaults to `10`.
+         */
        parallelismLimit?: number;
+        /**
+         * Defaults to `false`.
+         */
        legacyPathCasing?: boolean;
      };
    };