feat: improve documentation

Signed-off-by: ElaineDeMattosSilvaB <elaine.de-mattos-silva-bezerra@deutschebahn.com>

docs/integrations/gitlab/discovery.md

@@ -67,13 +67,18 @@ export default async function createPlugin(
   const builder = await CatalogBuilder.create(env);
   /* highlight-add-start */
   builder.addEntityProvider(
-    GitlabDiscoveryEntityProvider.fromConfig(env.config, {
+    ...GitlabDiscoveryEntityProvider.fromConfig(env.config, {
       logger: env.logger,
+      // optional: alternatively, use scheduler with schedule defined in app-config.yaml
+      schedule: env.scheduler.createScheduledTaskRunner({
+        frequency: { minutes: 30 },
+        timeout: { minutes: 3 },
+      }),
+      // optional: alternatively, use schedule
       scheduler: env.scheduler,
     }),
   );
   /* highlight-add-end */
-
   // ..
 }
 ```
@@ -108,6 +113,12 @@ export default async function createPlugin(
   /* highlight-add-start */
   const gitlabProvider = GitlabDiscoveryEntityProvider.fromConfig(env.config, {
     logger: env.logger,
+    // optional: alternatively, use scheduler with schedule defined in app-config.yaml
+    schedule: env.scheduler.createScheduledTaskRunner({
+      frequency: { minutes: 30 },
+      timeout: { minutes: 3 },
+    }),
+    // optional: alternatively, use schedule
     scheduler: env.scheduler,
   });
   env.eventBroker.subscribe(gitlabProvider);
@@ -123,16 +134,18 @@ export default async function createPlugin(
 
 To use the discovery provider, you'll need a GitLab integration
 [set up](locations.md) with a `token`. Then you can add a provider config per group
-to the catalog configuration:
+to the catalog configuration.
 
-```yaml
+> > NOTE: if you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
+
+```yaml title="app-config.yaml"
 catalog:
   providers:
     gitlab:
       yourProviderId:
         host: gitlab-host # Identifies one of the hosts set up in the integrations
         branch: main # Optional. Used to discover on a specific branch
-        fallbackBranch: main # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default
+        fallbackBranch: master # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default
         skipForkedRepos: false # Optional. If the project is a fork, skip repository
         group: example-group # Optional. Group and subgroup (if needed) to look for repositories. If not present the whole instance will be scanned
         entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml`

docs/integrations/gitlab/org.md

@@ -68,20 +68,27 @@ Add the plugin to the plugin catalog `packages/backend/src/plugins/catalog.ts`:
 /* highlight-add-next-line */
 import { GitlabOrgDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
 
-const builder = await CatalogBuilder.create(env);
-/** ... other processors and/or providers ... */
-/* highlight-add-start */
-builder.addEntityProvider(
-  ...GitlabOrgDiscoveryEntityProvider.fromConfig(env.config, {
-    logger: env.logger,
-    // optional: alternatively, use scheduler with schedule defined in app-config.yaml
-    schedule: env.scheduler.createScheduledTaskRunner({
-      frequency: { minutes: 30 },
-      timeout: { minutes: 3 },
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const builder = await CatalogBuilder.create(env);
+  /** ... other processors and/or providers ... */
+  /* highlight-add-start */
+  builder.addEntityProvider(
+    ...GitlabOrgDiscoveryEntityProvider.fromConfig(env.config, {
+      logger: env.logger,
+      // optional: alternatively, use scheduler with schedule defined in app-config.yaml
+      schedule: env.scheduler.createScheduledTaskRunner({
+        frequency: { minutes: 30 },
+        timeout: { minutes: 3 },
+      }),
+      // optional: alternatively, use schedule
+      scheduler: env.scheduler,
     }),
-  }),
-);
-/* highlight-add-end */
+  );
+  /* highlight-add-end */
+  // ..
+}
 ```
 
 #### Installation with Events Support
@@ -116,6 +123,12 @@ export default async function createPlugin(
     env.config,
     {
       logger: env.logger,
+      // optional: alternatively, use scheduler with schedule defined in app-config.yaml
+      schedule: env.scheduler.createScheduledTaskRunner({
+        frequency: { minutes: 30 },
+        timeout: { minutes: 3 },
+      }),
+      // optional: alternatively, use schedule
       scheduler: env.scheduler,
     },
   );
@@ -145,6 +158,8 @@ amount of data, this can take significant time and resources.
 The token used must have the `read_api` scope, and the Users and Groups fetched
 will be those visible to the account which provisioned the token.
 
+> > NOTE: if you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
+
 ```yaml
 catalog:
   providers:
@@ -153,7 +168,13 @@ catalog:
         host: gitlab.com
         orgEnabled: true
         group: org/teams # Required for gitlab.com when `orgEnabled: true`. Optional for self managed. Must not end with slash. Accepts only groups under the provided path (which will be stripped)
+        allowInherited: true # Allow groups to be ingested even if there are no direct members.
         groupPattern: '[\s\S]*' # Optional. Filters found groups based on provided pattern. Defaults to `[\s\S]*`, which means to not filter anything
+        schedule: # optional; same options as in TaskScheduleDefinition
+          # supports cron, ISO duration, "human duration" as used in code
+          frequency: { minutes: 30 }
+          # supports ISO duration, "human duration" as used in code
+          timeout: { minutes: 3 }
 ```
 
 ### Groups