Skip to content

Commit

Permalink
docs: fix grammar and style issues (#1974)
Browse files Browse the repository at this point in the history
* docs: fix grammar and style issues

* docs: fix e2e readme links
  • Loading branch information
kadel authored Nov 22, 2024
1 parent 606793a commit ac87113
Show file tree
Hide file tree
Showing 8 changed files with 50 additions and 51 deletions.
36 changes: 18 additions & 18 deletions docs/dynamic-plugins/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ For local debugging of Dynamic Plugins you need to clone `backstage-showcase`, r

* Build your plugin and export the dynamic package

```
```shell
cd ${pluginRootDir}
yarn build && yarn run export-dynamic
```
Expand All @@ -20,37 +20,37 @@ Once the plugin is built and deployed, it is time to prepare the showcase to run
* Run `yarn workspace backend start --inspect`
* In logs you should see something like the following:

```
```text
Debugger listening on ws://127.0.0.1:9229/9299bb26-3c32-4781-9488-7759b8781db5
```

* The application will be acessible from `http://localhost:7007`. You may start the front end by running the following command from the root directory: `yarn start --filter=app`. It will be available in `http://localhost:3000`
* Attach your IDE debugger to the backend process. This step may depend on the IDE that you are using. For example, if you are using VSCode you may want to check [Node.js debugging in VS Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging)
* Add Breakpoints to the files in folder `dynamic-plugins-root/${plugin-id}`. Optionally you can configure your IDE to add the source maps for the plugin so you can debug the TypeScript code directly and not the compiled Javascript files
* The application will be accessible from `http://localhost:7007`. You may start the front end by running the following command from the root directory: `yarn start --filter=app`. It will be available in `http://localhost:3000`
* Attach your IDE debugger to the backend process. This step may depend on the IDE that you are using. For example, if you are using VS Code you may want to check [Node.js debugging in VS Code](https://code.visualstudio.com/docs/nodejs/nodejs-debugging)
* Add Breakpoints to the files in folder `dynamic-plugins-root/${plugin-id}`. Optionally you can configure your IDE to add the source maps for the plugin so you can debug the TypeScript code directly and not the compiled JavaScript files

## Backend Dynamic Plugins Container Debug

It is possible to run RHDH on a container and debug plugins that are running on it. In this case you don't need to clone the `backstage-showcase` code locally, instead you must make sure that the running container has the [Node JS debug](https://nodejs.org/en/learn/getting-started/debugging) port open and exposed to the host machine. These are the steps to debug backend dynamic plugins on a container:
It is possible to run RHDH on a container and debug plugins that are running on it. In this case you don't need to clone the `backstage-showcase` code locally, instead you must make sure that the running container has the [Node.js debug](https://nodejs.org/en/learn/getting-started/debugging) port open and exposed to the host machine. These are the steps to debug backend dynamic plugins on a container:

* Create directory `dynamic-plugins-root`
* Build your plugin and copy the folder `dist-dynamic` to `dynamic-plugins-root`

```
$ yarn build && yarn export-dynamic
$ cp ${yourPluginRootDir}/dist-dynamic ./dynamic-plugins-root/${pluginID}
```shell
yarn build && yarn export-dynamic
cp ${yourPluginRootDir}/dist-dynamic ./dynamic-plugins-root/${pluginID}
```

* Start the container and make sure to share the plugins directory with it, allow inspect and open the debug port. Here's a sample command tested on RHDH container image version 1.3:
* Start the container and make sure to share the plugins directory with it, allow inspection and open the debug port. Here's a sample command tested on RHDH container image version 1.3:

```
```shell
podman run \
-v ./dynamic-plugins-root:/opt/app-root/src/dynamic-plugins-root:Z \
-v ./app-config.local.yaml:/opt/app-root/src/app-config.local.yaml:Z \
-p 7007:7007 \
-p 9229:9229 \
-e NODE_OPTIONS=--no-node-snapshot \
--entrypoint='["node", "--inspect=0.0.0.0:9229", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.example.yaml", "--config", "app-config.local.yaml"]' \
quay.io/rhdh/rhdh-hub-rhel9:1.3
-v ./dynamic-plugins-root:/opt/app-root/src/dynamic-plugins-root:Z \
-v ./app-config.local.yaml:/opt/app-root/src/app-config.local.yaml:Z \
-p 7007:7007 \
-p 9229:9229 \
-e NODE_OPTIONS=--no-node-snapshot \
--entrypoint='["node", "--inspect=0.0.0.0:9229", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.example.yaml", "--config", "app-config.local.yaml"]' \
quay.io/rhdh/rhdh-hub-rhel9:1.3
```

You should be able to debug from your IDE by attaching it to the process running on port `9229` or selecting it from a list of processes detected by the IDE.
Expand Down
10 changes: 5 additions & 5 deletions docs/dynamic-plugins/export-derived-package.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Export Derived Dynamic Plugin Package

In order to be able to use dynamic plugins in the RHDH, they need to be exported as a separate package. Which is than used by the RHDH to load the plugin.
In order to be able to use dynamic plugins in the RHDH, they need to be exported as a separate package. Which is then used by the RHDH to load the plugin.
Exporting a dynamic plugin package is a process of creating a new package that contains the plugin code and its dependencies, and is ready to be used as a dynamic plugin in the RHDH.

This document describes how to export a dynamic plugin package from an existing Backstage plugin.
Expand Down Expand Up @@ -50,7 +50,7 @@ The dynamic export mechanism identifies private, non-backstage dependencies, and
### Shared dependencies

During the exporting process some dependencies are marked as shared dependencies, and are expected to be provided by the main Backstage application. These dependencies are not bundled in the dynamic plugin package, but are marked as `peerDependencies` in the `package.json` file.
By default all the `@backstage`-scoped packages are considered shared packages.
By default, all the `@backstage`-scoped packages are considered shared packages.

Using `--shared-package` flag you can control which packages are considered shared packages.
Shared packages are expected to be provided by the main Backstage application, and are not bundled in the dynamic plugin package.
Expand All @@ -67,7 +67,7 @@ By default, all packages with `-node` or `-common` suffix are automatically embe
Using `--embed-package` flag you can control which packages are embedded in the dynamic plugin package.
The `--embed-package` flag can be used multiple times to specify multiple embedded packages.

If plugin depends on another package that is in the same monorepo workspace and it doesn't follow stadart naming convention (`-node`, or `-common`), you can use the `--embed-package` flag to embed it in the dynamic plugin package.
If a plugin depends on another package in the same monorepo workspace, and it doesn't follow standard naming convention (`-node`, or `-common`), you can use the `--embed-package` flag to embed it in the dynamic plugin package.

Example of exporting a dynamic plugin with shared and embedded packages:

Expand Down Expand Up @@ -95,7 +95,7 @@ Our CLI can generate the default configuration for Scalprum on the fly. For gene

//TODO document how to use a separate file for the Scalprum configuration which should be a preferred way to customize Scalprum's behavior.

However if you want to customize Scalprum's behavior, you can do so by including additional section to the `package.json` under `scalprum` key:
However, if you want to customize Scalprum's behavior, you can do so by including additional section to the `package.json` under `scalprum` key:

```json
...
Expand All @@ -111,7 +111,7 @@ However if you want to customize Scalprum's behavior, you can do so by including
...
```

Dynamic plugins may also need to adopt to specific Backstage needs like static JSX children for mountpoints and dynamic routes. These changes are strictly optional and exported symbols are incompatible with static plugins.
Dynamic plugins may also need to be adopted to specific Backstage needs like static JSX children for mount points and dynamic routes. These changes are strictly optional and exported symbols are incompatible with static plugins.

To include static JSX as element children with your dynamically imported component, please define an additional export as follows and use that as your dynamic plugin `importName`:

Expand Down
26 changes: 13 additions & 13 deletions docs/dynamic-plugins/frontend-plugin-wiring.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ plugins:
## Extend internal library of available icons
Backstage offers an internal catalog of system icons available across the application. This is traditionally used within Catalog items as icons for links for example. Dynamic plugins also use this catalog when fetching icons for [dynamically configured routes with sidebar navigation menu entry](#dynamic-routes). Therefore if a plugin requires a custom icon to be used for menu item, this icon must be added to the internal icon catalog. This is done via `appIcons` configuration:
Backstage offers an internal catalog of system icons available across the application. This is traditionally used within Catalog items as icons for links for example. Dynamic plugins also use this catalog when fetching icons for [dynamically configured routes with sidebar navigation menu entry](#dynamic-routes). Therefore, if a plugin requires a custom icon to be used for menu item, this icon must be added to the internal icon catalog. This is done via `appIcons` configuration:

```yaml
# dynamic-plugins-config.yaml
Expand Down Expand Up @@ -76,7 +76,7 @@ Traditionally, [Backstage full page extensions](https://backstage.io/docs/plugin

This change is usually coupled with an extension to the main sidebar navigation, achieved by editing `packages/app/src/components/Root/Root.tsx`.

In dynamic plugins this mechanism has changed and users are no longer allowed to edit `.tsx` files. Instead they declare their desire to expose additional routes within dynamic plugin configuration:
In dynamic plugins this mechanism has changed and users are no longer allowed to edit `.tsx` files. Instead, they declare their desire to expose additional routes within dynamic plugin configuration:

```yaml
# dynamic-plugins-config.yaml
Expand All @@ -100,16 +100,16 @@ plugins:
Each plugin can expose multiple routes and each route is required to define its `path` and `importName` (if it differs from the default export).

- `path` - Unique path in the app. Cannot override existing routes with the exception of the `/` home route: the main home page can be replaced via the dynamic plugins mechanism.
- `path` - Unique path in the app. Cannot override existing routes except the `/` home route: the main home page can be replaced via the dynamic plugins mechanism.
- `module` - Optional. Since dynamic plugins can expose multiple distinct modules, you may need to specify which set of assets you want to access within the plugin. If not provided, the default module named `PluginRoot` is used. This is the same as the key in `scalprum.exposedModules` key in plugin's `package.json`.
- `importName` - Optional. The actual component name that should be rendered as a standalone page. If not specified the `default` export is used.
- `menuItem` - This property allows users to extend the main sidebar navigation and point to their new route. It accepts the following properties:
- `text`: The label shown to the user
- `icon`: refers to a Backstage system icon name. See [Backstage system icons](https://backstage.io/docs/getting-started/app-custom-theme/#icons) for the list of default icons and [Extending Icons Library](#extend-internal-library-of-available-icons) to extend this with dynamic plugins.
- `importName`: optional name of an exported SidebarItem component. The component will receive a `to` property as well as any properties specified in `config.props`
- `importName`: optional name of an exported `SidebarItem` component. The component will receive a `to` property as well as any properties specified in `config.props`
- `config` - An optional field which is a holder to pass `props` to a custom sidebar item

A custom SidebarItem offers opportunities to provide a richer user experience such as notification badges. The component should accept the following properties:
A custom `SidebarItem` offers opportunities to provide a richer user experience such as notification badges. The component should accept the following properties:

```typescript
export type MySidebarItemProps = {
Expand All @@ -119,7 +119,7 @@ export type MySidebarItemProps = {

Other properties can be specified as well and configured using the `config.props` property on the dynamic route.

Here is an example configuration specifying a custom SidebarItem component:
Here is an example configuration specifying a custom `SidebarItem` component:

```yaml
# dynamic-plugins-config.yaml
Expand Down Expand Up @@ -163,7 +163,7 @@ plugins:
Up to 3 levels of nested menu items are supported.
- <menu_item_name> - A unique name in the main sidebar navigation. This can represent either a standalone menu item or a parent menu item. If it represents a plugin menu item, the name must match the corresponding path in `dynamicRoutes`. For example, if dynamicRoutes defines `path: /my-plugin`, the `menu_item_name` must be `my-plugin`.
- <menu_item_name> - A unique name in the main sidebar navigation. This can represent either a standalone menu item or a parent menu item. If it represents a plugin menu item, the name must match the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, the `menu_item_name` must be `my-plugin`.

- Handling Complex Paths:
- For simple paths like `path: /my-plugin`, the `menu_item_name` should be `my-plugin`.
Expand Down Expand Up @@ -287,7 +287,7 @@ The following mount points are available:
| `search.page.filters` | Search filters | YES, default catalog kind and lifecycle filters are visible |
| `search.page.results` | Search results content | YES, default catalog search is present |

Mount points within Catalog aka `entity.page.*` are rendered as tabs. They become visible only if at least one plugin contributes to them or they can render static content (see column 3 in previous table).
Mount points within Catalog aka `entity.page.*` are rendered as tabs. They become visible only if at least one plugin contributes to them, or they can render static content (see column 3 in previous table).

Each `entity.page.*` mount point has 2 complementary variations:

Expand Down Expand Up @@ -337,7 +337,7 @@ Each mount point supports additional configuration:
- `isKind`: Accepts a string or a list of string with entity kinds. For example `isKind: component` will render the component only for entity of `kind: Component`.
- `isType`: Accepts a string or a list of string with entity types. For example `isType: service` will render the component only for entities of `spec.type: 'service'`.
- `hasAnnotation`: Accepts a string or a list of string with annotation keys. For example `hasAnnotation: my-annotation` will render the component only for entities that have `metadata.annotations['my-annotation']` defined.
- condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` will render the component only if `isMyPluginAvailable` function returns `true`. The function must have following signature: `(e: Entity) => boolean`
- Condition imported from the plugin's `module`: Must be function name exported from the same `module` within the plugin. For example `isMyPluginAvailable` will render the component only if `isMyPluginAvailable` function returns `true`. The function must have the following signature: `(e: Entity) => boolean`

The entity page also supports adding more items to the context menu at the top right of the page. Components targeting the `entity.context.menu` mount point have some constraints to follow. The exported component should be some form of dialog wrapper component that accepts an `open` boolean property and an `onClose` event handler property, like so:

Expand Down Expand Up @@ -427,10 +427,10 @@ The visibility of a tab is derived from the kind of entity that is being display

### Provide additional Utility APIs

Backstage offers an Utility API mechanism that provide ways for plugins to communicate during their entire life cycle. Utility APIs are registered as:
Backstage offers a Utility API mechanism that provide ways for plugins to communicate during their entire life cycle. Utility APIs are registered as:

- Core APIs, which are always present in any Backstage application
- Custom plugin-made API that can be already self contained within any plugin (including dynamic plugins)
- Custom plugin-made API that can be already self-contained within any plugin (including dynamic plugins)
- [App API implementations and overrides](https://backstage.io/docs/api/utility-apis/#app-apis) which needs to be added separately.

and a plugin can potentially expose multiple API Factories. Dynamic plugins allow a couple different ways to take advantage of this functionality.
Expand All @@ -444,7 +444,7 @@ dynamicPlugins:
my-dynamic-plugin-package-with-api-factories: {}
```

However if the dynamic plugin doesn't export it's plugin object then it will be necessary to explicitly configure each API factory that should be registered with the `createApp` API via the `apiFactories` configuration:
However, if the dynamic plugin doesn't export it's plugin object then it will be necessary to explicitly configure each API factory that should be registered with the `createApp` API via the `apiFactories` configuration:

```yaml
# app-config.yaml
Expand Down Expand Up @@ -485,7 +485,7 @@ dynamicPlugins:
- importName: customScmAuthApiFactory
```

which would override the default ScmAuth API factory that DeveloperHub defaults to.
which would override the default `ScmAuth` API factory that Developer Hub defaults to.

### Provide custom Scaffolder field extensions

Expand Down
Loading

0 comments on commit ac87113

Please sign in to comment.