[release-1.5] RHIDP-5422: TechDocs add-ons doc

assemblies/assembly-configuring-techdocs.adoc

@@ -1,7 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 :context: configuring-techdocs
 [id="{context}"]
-= Configuring TechDocs
+= TechDocs configuration
 
 The TechDocs plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the {product} Helm chart or the {product} Operator ConfigMap.
 

assemblies/assembly-techdocs-addons-installing.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+:context: techdocs-addon-installing
+[id="techdocs-addon-installing"]
+= Installing and configuring a TechDocs add-on
+
+TechDocs add-ons are supported by {company-name} are imported by the `backstage-plugin-techdocs-module-addons-contrib` plugin package. The `<ReportIssue />` add-on is preinstalled in the TechDocs plugin and enabled by default. You can install external TechDocs add-ons by adding them to `backstage-plugin-techdocs-module-addons-contrib` package with either the {product} Operator or Helm chart. Additionally, you can import compatible third-party add-ons, including add-ons that you create yourself, with a third-party dynamic plugin.
+
+include::modules/techdocs/proc-techdocs-addon-install-operator.adoc[]
+
+include::modules/techdocs/proc-techdocs-addon-install-helm.adoc[]
+
+include::modules/techdocs/proc-techdocs-addon-install-third-party.adoc[]
+
+.Additional resources
+* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about[Installing dynamic plugins in Red Hat Developer Hub]
+* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/assembly-third-party-plugins[Third-party plugins in Red Hat Developer Hub]

assemblies/assembly-techdocs-addons-removing.adoc

@@ -0,0 +1,12 @@
+:_mod-docs-content-type: ASSEMBLY
+:context: techdocs-addon-removing
+[id="techdocs-addon-removing"]
+= Removing a TechDocs add-on
+
+Administrators can remove installed TechDocs add-ons from your {product} instance by using either the Operator or Helm chart, depending on the method used to install the add-on. If you used the Operator to install the add-on, remove it from the ConfigMap. If you used the Helm chart to install the add-on, remove it from the Helm chart.
+
+If you want to disable a plugin instead of removing it from your {product} instance, you can disable the plugin that you are using to import the TechDocs add-on. Since the `disabled` status is controlled at the plugin level, disabling the plugin disables all of the TechDocs add-ons in the specified plugin package.
+
+include::modules/techdocs/proc-techdocs-addon-remove-operator.adoc[]
+
+include::modules/techdocs/proc-techdocs-addon-remove-helm.adoc[]

assemblies/assembly-techdocs-addons-using.adoc

@@ -0,0 +1,12 @@
+:_mod-docs-content-type: ASSEMBLY
+:context: techdocs-addon-using
+[id="techdocs-addon-using"]
+= Using TechDocs add-ons
+
+After an administrator installs a TechDocs add-on in your {product} instance, you can use it to extend the functionality of the TechDocs plugin and enhance your documentation experience.
+
+include::modules/techdocs/proc-techdocs-addon-use-report-issue.adoc[]
+
+include::modules/techdocs/proc-techdocs-addon-use-text-size.adoc[]
+
+include::modules/techdocs/proc-techdocs-addon-use-light-box.adoc[]

assemblies/assembly-techdocs-addons.adoc

@@ -0,0 +1,34 @@
+:_mod-docs-content-type: ASSEMBLY
+:context: techdocs-addon
+[id="techdocs-addon"]
+= TechDocs add-ons
+
+TechDocs add-ons are dynamic plugins that extend the functionality of the built-in TechDocs plugin. For example, you can use add-ons to report documentation issues, change text size, or view images in overlay in either the TechDocs Reader page or an Entity page.
+
+The following table describes the TechDocs add-ons that are available for {product} {product-version}:
+
+.TechDocs Add-ons available in {product}
+|===
+| TechDocs Add-on  | Package/Plugin | Description | Type
+
+| `<ReportIssue />`
+| `backstage-plugin-techdocs-module-addons-contrib`
+| Select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation. The issue template is automatically populated with the selected text.
+| Preinstalled
+
+| `<TextSize />`
+| `backstage-plugin-techdocs-module-addons-contrib`
+| Customize text size on documentation pages by increasing or decreasing the font size with a 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.
+| External
+
+| `<LightBox />`
+| `backstage-plugin-techdocs-module-addons-contrib`
+| Open images in a light-box on documentation pages, to navigate to multiple images on a single page. The image size of the light-box image is the same as the image size on the document page. Clicking the zoom icon increases the image size to fit the screen.
+| External
+
+//future release | `<ExpandableNavigation />`
+//future release | `backstage-plugin-techdocs-module-addons-contrib`
+//future release | Expand or collapse the subtitles in the TechDocs navigation menu and keep your preferred state between documentation sites.
+|===
+
+You can use a dynamic plugin to import a TechDocs add-on. TechDocs add-ons are enabled at the plugin level, therefore, enabling a plugin enables all of the TechDocs add-ons in the specified plugin package. The preinstalled and external add-ons supported by {company} are imported by the `backstage-plugin-techdocs-module-addons-contrib` plugin package. Since the `disabled` status is set at the plugin level, the `disabled` status of the plugin package applies to all of the TechDocs add-ons imported by that package.

modules/techdocs/con-techdocs-about.adoc

@@ -18,4 +18,4 @@ Built-in navigation and search::
 Locate the information that you need within a document quickly and easily.
 
 Add-ons::
-Customize your TechDocs experience with add-ons to address higher-order documentation needs.
+Make your documentation more functional and interactive with supported TechDocs add-ons. Some add-ons are preinstalled and enabled by default. To extend the default functionality, you can dynamically load external and third-party add-ons into your {product} instance. If you want to further customize your TechDocs experience, you can create add-ons that meet specific documentation needs for your organization.

modules/techdocs/proc-techdocs-addon-create.adoc

@@ -0,0 +1,149 @@
+// Module included in the following assemblies:
+//
+// [WIP] file created but not currently part of any assembly or title
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-addon-create_{context}"]
+== Creating a TechDocs add-on
+
+If your organization has documentation needs that are not met by the functions of existing TechDocs add-ons, developers can create a new add-on for your TechDocs plugin.
+
+A TechDocs add-on is a React component that is imported from a front-end plugin. If you do not have an existing plugin that you can use to export your TechDocs add-on, you can create a new plugin by using `backstage-cli` to generate a default front-end plugin structure that you can customize.
+
+The folder structure of a new plugin that can be used to import TechDocs add-ons into the TechDocs plugin looks similar to the following example:
+[source,json,subs="+attributes,+quotes"]
+----
+_<new_plugin_for_techdocs_add-on>_/
+   dev/
+       index.ts
+   src/
+       components/
+         _<new_techdocs_add-on_component>_/
+              _<new_techdocs_add-on_component>_.test.tsx
+              _<new_techdocs_add-on_component>_.tsx
+               index.ts
+         _<new_techdocs_add-on_fetch-component>_/
+              _<new_techdocs_add-on_fetch-component>_.test.tsx
+              _<new_techdocs_add-on_fetch-component>_.tsx
+               index.ts
+       index.ts
+       plugin.test.ts
+       plugin.ts
+       routes.ts
+       setupTests.ts
+   .eslintrc.js
+   package.json
+   README.md
+----
+
+.Prerequisites
+* The `yarn` package manager is installed.
+* Docker v3.2.0 or later or Podman v3.2.0 or later is installed and running.
+
+.Procedure
+. In the terminal, navigate to the root folder of the repository where you want to create your new plugin.
+. To create a new front-end plugin, run the following command:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+yarn new
+----
+.Example output
++
+[source,terminal,subs="+quotes"]
+----
+? What do you want to create? plugin - A new frontend plugin
+? Enter the ID of the plugin [required]
+----
++
+. In the terminal prompt, type a name for the new plugin. For example:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+? Enter the ID of the plugin [required] _<new_plugin_for_techdocs_add-on>_
+----
++
+.Example output
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+Successfully created plugin
+----
++
+.Result
+In the `plugins` directory, a sub-directory with the same name that you gave to your plugin is automatically generated. The directory contains all of the files that you need to configure to create your new plugin.
++
+. In the terminal, navigate to your new plugin directory. For example:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+cd plugins/_<new_techdocs_add-on_directory>_
+----
+. Add the`@backstage/plugin-techdocs-react` package to get frontend utilities for TechDocs add-ons. For example:
++
+[source,terminal,subs="+attributes,+quotes"]
+----
+yarn add @backstage/plugin-techdocs-react
+----
+. In the directory containing the components of your custom TechDocs add-on, delete any default files or file components that are not required for your add-on, such as the `routes.ts` file or components of the `index.tsx` and `plugins.ts` files.
+. In the `plugins.ts` file, add the following code:
++
+[source,java,subs="+attributes,+quotes"]
+----
+import { createPlugin } from '@backstage/core-plugin-api';
+import { createTechDocsAddonExtension } from '@backstage/plugin-techdocs-react';
+
+export const _<new_plugin_for_techdocs_add-on>_ = createPlugin({
+  id: '_<new_techdocs_add-on>_',
+ });
+
+ /*
+ *
+ * @public
+ */
+export const _<new_techdocs_add-on>_ = _<new_plugin_for_techdocs_add-on>_.provide(
+ createTechDocsAddonExtension<_<new_techdocs_addon_props>_>({
+    name: '_<new_techdocs_add-on>_',
+    location: TechDocsAddonLocations.Content,
+    component: _<new_techdocs_add-on_component>_,
+  }),
+);
+----
++
+where
+
+_<new_plugin_for_techdocs_add-on>_ :: Specifies the new plugin that you use to import the TechDocs add-on to your {product} instance.
+_<new_techdocs_add-on>_ :: Specifies the custom TechDocs add-on that you want to create.
+_<new_techdocs_addon_props>_ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `_<new_techdocs_add-on>_.tsx` file, if applicable.
+_<new_techdocs_add-on_component>_ :: Specifies the React component for the custom TechDocs add-on that you want to create. You will create this component in a `.tsx` file in a later step.
+. In the `index.ts` file, export the custom TechDocs add-on that you want to create by adding the following code:
++
+[source,java,subs="+attributes,+quotes"]
+----
+export { _<new_plugin_for_techdocs_add-on>_, _<new_techdocs_add-on>_ } from './plugin';
+----
+. Create a new `_<new_techdocs_add-on>_.tsx` file and add the code for your new TechDocs add-on component.
++
+////
+[source,java,subs="+attributes,+quotes"]
+----
+can add example code for this file, if helpful
+can also mention a template that the user can configure, if there is one
+----
+////
+. Create a new `index.tsx` file and use it to export your new TechDocs add-on component by adding the following code:
++
+[source,java,subs="+attributes,+quotes"]
+----
+export { _<new_techdocs_add-on>_, type _<new_techdocs_addon_props>_} from './_<new_techdocs_add-on_directory>_'
+----
++
+where
+
+_<new_techdocs_addon_props>_ (Optional) :: Specifies the `props` for your new TechDocs add-on, as specified in your `_<new_techdocs_add-on>_.tsx` file, if applicable.
+. In the `plugins.ts` file, import your new TechDocs add-on component.
+. Install and configure your new TechDocs add-on by following the steps in link:{techdocs-book-url}#techdocs-addon-installing[Installing and configuring a TechDocs add-on]
+
+.Verification
+. Restart the RHDH application and verify that the plugin is successfully activated and configured.
+. Verify the application logs for confirmation and ensure the plugin is functioning as expected.

modules/techdocs/proc-techdocs-addon-install-helm.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-techdocs-addons-installing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-addon-install-helm_{context}"]
+== Installing and configuring an external TechDocs add-on using the Helm chart
+
+You can use a dynamic plugin to import TechDocs add-ons into your TechDocs plugin. If you use the {product} Helm chart to install the dynamic plugin, you can add TechDocs add-ons to the plugin package in your Helm chart.
+
+Preinstalled add-ons, such as `ReportIssue`, are included in the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. External add-ons that are supported by {company-name} are installed by manually adding them to the `techdocsAddons` section of the configuration file.
+
+.Prerequisites
+* The TechDocs plugin is installed and enabled.
+
+.Procedure
+. In your Helm chart, add the `global.dynamic` parameters required to install a dynamic plugin, as shown in link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about#con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[Installing dynamic plugins using the Helm chart ]
++
+[NOTE]
+====
+The default configuration includes the `dynamic-plugins.default.yaml` file, which contains all of the dynamic plugins, including TechDocs add-ons, that are preinstalled in {product}, whether they are enabled or disabled by default.
+====
+. In your Helm chart, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+global:
+  dynamic:
+    plugins:
+      - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
+        disabled: false
+        pluginConfig:
+          dynamicPlugins:
+            frontend:
+              backstage.plugin-techdocs-module-addons-contrib:
+                techdocsAddons:
+                  - importName: ReportIssue
+----
+. In the `techdocsAddons` section of the Helm chart, add `importName: _<external_techdocs_add-on>_` for each external TechDocs add-on that you want to add from the specified plugin package. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+global:
+  dynamic:
+    plugins:
+      - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
+        disabled: false
+        pluginConfig:
+          dynamicPlugins:
+            frontend:
+              backstage.plugin-techdocs-module-addons-contrib:
+                techdocsAddons:
+                  - importName: ReportIssue
+                  - importName: _<external_techdocs_add-on>_
+----
++
+where:
+
+_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize` or `LightBox`.
+
+//.Next steps

modules/techdocs/proc-techdocs-addon-install-operator.adoc

@@ -0,0 +1,91 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-techdocs-addons-installing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-addon-install-operator_{context}"]
+== Installing and configuring an external TechDocs add-on using the Operator
+
+You can use a dynamic plugin to import TechDocs add-ons into your TechDocs plugin. If you use the {product} Operator to install the dynamic plugin, you can add TechDocs add-ons to the plugin package in your ConfigMap.
+
+Preinstalled add-ons, such as `ReportIssue`, are included in the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. External add-ons that are supported by {company-name} are installed by manually adding them to the `techdocsAddons` section of the configuration file.
+
+.Procedure
+
+. From the Developer perspective in the {ocp-short} web console, click *ConfigMaps* > *Create ConfigMap*.
+. From the *Create ConfigMap* page, select the *YAML view* option in the *Configure via* field.
+. In the newly created ConfigMap, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: dynamic-plugins-rhdh
+data:
+  dynamic-plugins.yaml: |
+    includes:
+      - dynamic-plugins.default.yaml
+    plugins:
+      - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
+        disabled: false
+        pluginConfig:
+          dynamicPlugins:
+            frontend:
+              backstage.plugin-techdocs-module-addons-contrib:
+                techdocsAddons:
+                  - importName: ReportIssue
+----
+. In the `techdocsAddons` section of the ConfigMap, add `importName: _<external_techdocs_add-on>_` for each external TechDocs add-on that you want to add from the specified plugin package. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: dynamic-plugins-rhdh
+data:
+  dynamic-plugins.yaml: |
+    includes:
+      - dynamic-plugins.default.yaml
+    plugins:
+      - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
+        disabled: false
+        pluginConfig:
+          dynamicPlugins:
+            frontend:
+              backstage.plugin-techdocs-module-addons-contrib:
+                techdocsAddons:
+                  - importName: ReportIssue
+                  - importName: _<external_techdocs_add-on>_
+----
++
+where:
+
+_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize` or `LightBox`.
+. Click *Create*.
+. In the web console navigation menu, click *Topology*.
+. Click on the overflow menu for the {product} instance that you want to use and select *Edit Backstage* to load the YAML view of the {product} instance.
+. In your `{product-custom-resource-type}` CR, add the `dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_` key-value pair. For example:
++
+[source,yaml]
+----
+apiVersion: rhdh.redhat.com/v1alpha3
+kind: Backstage
+metadata:
+  name: my-rhdh
+spec:
+  application:
+# ...
+    dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_
+# ...
+----
++
+where:
+
+_<dynamic_plugins_configmap>_:: Specifies the name of your dynamic plugins ConfigMap for your {product} instance, for example, `dynamic-plugins-rhdh`.
+. Click *Save*.
+. In the web console navigation menu, click *Topology* and wait for the {product} pod to start.
+. Click the *Open URL* icon to start using the {product} platform with the new configuration changes.
+
+//.Next steps