Skip to content

Commit d6031a5

Browse files
linfrazelinfraze
committed
RHIDP-5422: TechDocs add-ons doc
1 parent 78e21c3 commit d6031a5

16 files changed

+503
-2
lines changed

‎assemblies/assembly-configuring-techdocs.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
:_mod-docs-content-type: ASSEMBLY
22
:context: configuring-techdocs
33
[id="{context}"]
4-
= Configuring TechDocs
4+
= TechDocs configuration
55

66
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.
77

‎assemblies/assembly-techdocs-addons-installing.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:context: techdocs-addon-installing
3+
[id="techdocs-addon-installing"]
4+
= Installing TechDocs add-ons
5+
6+
The `<ReportIssue />` add-on is preinstalled in your {product} instance and enabled by default. Like any other supported dynamic plugin, you can install external TechDocs add-ons by using either the Operator or Helm chart. Additionally, you can import compatible third-party add-ons, including add-ons that you create yourself, the same way that you import any other third-party dynamic plugin into {product}.
7+
8+
include::modules/techdocs/proc-techdocs-addon-install-operator.adoc[]
9+
10+
include::modules/techdocs/proc-techdocs-addon-install-helm.adoc[]
11+
12+
include::modules/techdocs/proc-techdocs-addon-install-third-party.adoc[]
13+
14+
.Additional resources
15+
* 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]
16+
* 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‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:context: techdocs-addon-removing
3+
[id="techdocs-addon-removing"]
4+
= Removing a TechDocs add-on
5+
6+
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.
7+
8+
include::modules/techdocs/proc-techdocs-addon-remove-operator.adoc[]
9+
10+
include::modules/techdocs/proc-techdocs-addon-remove-helm.adoc[]

‎assemblies/assembly-techdocs-addons-using.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:context: techdocs-addon-using
3+
[id="techdocs-addon-using"]
4+
= Using TechDocs add-ons
5+
6+
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.
7+
8+
include::modules/techdocs/proc-techdocs-addon-use-report-issue.adoc[]
9+
10+
include::modules/techdocs/proc-techdocs-addon-use-text-size.adoc[]
11+
12+
include::modules/techdocs/proc-techdocs-addon-use-light-box.adoc[]

‎assemblies/assembly-techdocs-addons.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:context: techdocs-addon
3+
[id="techdocs-addon"]
4+
= TechDocs add-ons
5+
6+
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.
7+
8+
The following table describes the TechDocs add-ons that are available for {product} {product-version}:
9+
10+
.TechDocs Add-ons available in {product}
11+
|===
12+
| TechDocs Add-on | Package/Plugin | Description | Type
13+
14+
| `<ReportIssue />`
15+
| `backstage-plugin-techdocs-module-addons-contrib`
16+
| 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.
17+
| Preinstalled
18+
19+
| `<TextSize />`
20+
| `backstage-plugin-techdocs-module-addons-contrib`
21+
| 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.
22+
| External
23+
24+
| `<LightBox />`
25+
| `backstage-plugin-techdocs-module-addons-contrib`
26+
| 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.
27+
| External
28+
29+
//future release | `<ExpandableNavigation />`
30+
//future release | `backstage-plugin-techdocs-module-addons-contrib`
31+
//future release | Expand or collapse the subtitles in the TechDocs navigation menu and keep your preferred state between documentation sites.
32+
|===

‎modules/techdocs/con-techdocs-about.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,4 @@ Built-in navigation and search::
1818
Locate the information that you need within a document quickly and easily.
1919

2020
Add-ons::
21-
Customize your TechDocs experience with add-ons to address higher-order documentation needs.
21+
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‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Module included in the following assemblies:
2+
//
3+
// [WIP] file created but not currently part of any assembly or title
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-techdocs-addon-create_{context}"]
7+
== Creating a TechDocs add-on
8+
9+
You can create your own third-party TechDocs add-on for your {product} instance as a front-end dynamic plugin.
10+
11+
////
12+
.Prerequisites
13+
* The third-party TechDocs add-on has a valid `package.json` file in its root directory, containing all required metadata and dependencies.
14+
* You have installed the @janus-idp/cli package.
15+
* You have installed and configured Node.js and NPM.
16+
* You have installed the `scalprum` CLI tool for configuring front-end plugins.
17+
18+
.Procedure
19+
////

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-techdocs-addons-installing.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-techdocs-addon-install-helm_{context}"]
7+
== Installing and configuring an external TechDocs add-on using the Helm chart
8+
9+
You can use the {product} Helm chart to install a TechDocs add-on on your {product} instance as a dynamic plugin.
10+
11+
.Procedure
12+
. 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 ]
13+
. In your Helm chart, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example:
14+
+
15+
[source,yaml,subs="+quotes,+attributes"]
16+
----
17+
global:
18+
dynamic:
19+
plugins:
20+
- package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
21+
disabled: false
22+
pluginConfig:
23+
dynamicPlugins:
24+
frontend:
25+
backstage.plugin-techdocs-module-addons-contrib:
26+
techdocsAddons:
27+
- importName: ReportIssue
28+
----
29+
+
30+
[NOTE]
31+
====
32+
The `ReportIssue` TechDocs add-on is preinstalled and enabled by default, and therefore, it is included in the default package configuration.
33+
====
34+
35+
. In the `techdocsAddons` section of the Helm chart, add `importName: _<external_techdocs_add-on>` for each external TechDocs add-on that you want to install. For example:
36+
+
37+
[source,yaml,subs="+quotes,+attributes"]
38+
----
39+
global:
40+
dynamic:
41+
plugins:
42+
- package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
43+
disabled: false
44+
pluginConfig:
45+
dynamicPlugins:
46+
frontend:
47+
backstage.plugin-techdocs-module-addons-contrib:
48+
techdocsAddons:
49+
- importName: ReportIssue
50+
- importName: _<external_techdocs_add-on>_
51+
----
52+
+
53+
where:
54+
55+
_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize`.
56+
57+
//.Next steps

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

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-techdocs-addons-installing.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-techdocs-addon-install-operator_{context}"]
7+
== Installing and configuring a TechDocs add-on using the Operator
8+
9+
You can use the {product} Operator to install a TechDocs add-on on your {product} instance as a dynamic plugin.
10+
11+
.Prerequisites
12+
* An administrator has installed the {product} Operator.
13+
* You have installed the TechDocs plugin.
14+
15+
.Procedure
16+
17+
. From the Developer perspective in the {ocp-short} web console, click *ConfigMaps* > *Create ConfigMap*.
18+
. From the *Create ConfigMap* page, select the *YAML view* option in the *Configure via* field.
19+
. In the the {product} ConfigMap, add the default `backstage-plugin-techdocs-module-addons-contrib` package configuration. For example:
20+
+
21+
[source,yaml,subs="+quotes,+attributes"]
22+
----
23+
kind: ConfigMap
24+
apiVersion: v1
25+
metadata:
26+
name: dynamic-plugins-rhdh
27+
data:
28+
dynamic-plugins.yaml: |
29+
includes:
30+
- dynamic-plugins.default.yaml
31+
plugins:
32+
- package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
33+
disabled: false
34+
pluginConfig:
35+
dynamicPlugins:
36+
frontend:
37+
backstage.plugin-techdocs-module-addons-contrib:
38+
techdocsAddons:
39+
- importName: ReportIssue
40+
----
41+
+
42+
[NOTE]
43+
====
44+
The `ReportIssue` TechDocs add-on is preinstalled and enabled by default, and therefore, it is included in the default package configuration.
45+
====
46+
. In the `techdocsAddons` section of the ConfigMap, add `importName: _<external_techdocs_add-on>` for each external TechDocs add-on that you want to install. For example:
47+
+
48+
[source,yaml,subs="+quotes,+attributes"]
49+
----
50+
kind: ConfigMap
51+
apiVersion: v1
52+
metadata:
53+
name: dynamic-plugins-rhdh
54+
data:
55+
dynamic-plugins.yaml: |
56+
includes:
57+
- dynamic-plugins.default.yaml
58+
plugins:
59+
- package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
60+
disabled: false
61+
pluginConfig:
62+
dynamicPlugins:
63+
frontend:
64+
backstage.plugin-techdocs-module-addons-contrib:
65+
techdocsAddons:
66+
- importName: ReportIssue
67+
- importName: _<external_techdocs_add-on>_
68+
----
69+
+
70+
where:
71+
72+
_<external_techdocs_add-on>_:: Specifies the external TechDocs add-on that you want to install, for example, `TextSize`.
73+
. Click *Create*.
74+
. In the web console navigation menu, click *Topology*.
75+
. 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.
76+
. In your `{product-custom-resource-type}` CR, add the `dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_` key-value pair. For example:
77+
+
78+
[source,yaml]
79+
----
80+
apiVersion: rhdh.redhat.com/v1alpha3
81+
kind: Backstage
82+
metadata:
83+
name: my-rhdh
84+
spec:
85+
application:
86+
# ...
87+
dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_
88+
# ...
89+
----
90+
+
91+
where:
92+
93+
_<dynamic_plugins_configmap>_:: Specifies the name of your dynamic plugins ConfigMap for your {product} instance, for example, `dynamic-plugins-rhdh`.
94+
. Click *Save*.
95+
. In the web console navigation menu, click *Topology* and wait for the {product} pod to start.
96+
. Click the *Open URL* icon to start using the {product} platform with the new configuration changes.
97+
98+
//.Next steps

‎modules/techdocs/proc-techdocs-addon-install-third-party.adoc‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-techdocs-addons-installing.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-techdocs-addon-install-third-party_{context}"]
7+
== Installing and configuring a third-party TechDocs add-on
8+
9+
You can install compatible third-party TechDocs add-on on your {product} instance as a front-end dynamic plugin.
10+
11+
.Prerequisites
12+
* The third-party TechDocs add-on has a valid `package.json` file in its root directory, containing all required metadata and dependencies.
13+
* You have installed the @janus-idp/cli package.
14+
* You have installed and configured Node.js and NPM.
15+
* You have installed the `scalprum` CLI tool for configuring front-end plugins.
16+
17+
.Procedure
18+
. Obtain the source code for the third-party TechDocs add-on that you want to use.
19+
. Export the TechDocs add-on as a dynamic plugin using the following command:
20+
+
21+
[source,terminal,subs="+quotes,+attributes"]
22+
----
23+
npx @janus-idp/cli@latest package export-dynamic-plugin
24+
----
25+
+
26+
[NOTE]
27+
====
28+
The `@latest` tag uses the latest version of the `package.json` file for compatibility with the most recent features and fixes.
29+
====
30+
+
31+
.Example output
32+
[source,terminal,subs="+quotes,+attributes"]
33+
----
34+
Using scalpum config inlined in the `package.json`
35+
Packing main package to dist-dynamic/package.json
36+
Customizing main package in dist-dynamic/package.json for dynamic loading
37+
Generating dynamic frontend plugin assets in _<path_to_add-on_package>_/_<third-party_add-on_package>_/dist-dynamic/dist-scalprum
38+
...
39+
----
40+
+
41+
where
42+
43+
_<path_to_add-on_package>_ :: Specifies the package for the third-party add-on that you want to export, for example, `backstage-plugin-techdocs-module-addon-mermaid`.
44+
45+
. To package the third-party TechDocs add-on as a dynamic plugin, navigate to the root directory where the plugin is stored (not the dist-dynamic directory) and run the `npx` command with the `--tag` option to specify the image name and tag. For example:
46+
+
47+
[source,terminal,subs="+quotes,+attributes"]
48+
----
49+
npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
50+
----
51+
+
52+
[NOTE]
53+
====
54+
The output of the package-dynamic-plugins command provides the file path to the plugin for use in the `dynamic-plugin-config.yaml` file.
55+
====
56+
+
57+
. To publish the third-party TechDocs add-on to a Quay repository, push the image to a registry using one of the following commands, depending on your virtualization tool:
58+
* To use `podman`, enter the following command:
59+
+
60+
[source,terminal,subs="+quotes,+attributes"]
61+
----
62+
podman push quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
63+
----
64+
* To use `docker`, enter the following command:
65+
+
66+
[source,terminal,subs="+quotes,+attributes"]
67+
----
68+
docker push quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
69+
----
70+
. Open your `dynamic-plugins.yaml` file to view or modify the configuration for the third-party TechDocs add-on. For example:
71+
+
72+
[source,yaml,subs="+quotes,+attributes"]
73+
----
74+
plugins:
75+
- package: oci://quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest!_<techdocs_add-on_package>_
76+
disabled: false
77+
pluginConfig:
78+
dynamicPlugins:
79+
frontend:
80+
_<techdocs_add-on_package>_
81+
techdocsAddons:
82+
- importName: _<third-party_add-on_name>_
83+
config:
84+
props:
85+
config:
86+
theme: _<theme_name>_
87+
themeVariables: { lineColor: "_<line_color_variable>_"}
88+
----
89+
+
90+
where
91+
92+
_<user_name>>_ :: Specifies your Quay user name or organization name.
93+
_<techdocs_add-on_image>_ :: Specifies the name of the image for the third-party add-on that you want to use, for example, `mermaid`.
94+
_<techdocs_add-on_package>_ :: Specifies the , for example, `backstage-plugin-techdocs-addon-mermaid`.
95+
_<third-party_add-on_name>_ :: Specifies the name of the third-party add-on that you want to use, for example, `Mermaid`.
96+
_<theme_name>_ :: Specifies the name of the visual theme that you want to apply to your third-party TechDocs add-on, for example, `forest`. Depending on the third-party add-on, this field can be optional or required.
97+
_<line_color_variable>_ :: Specifies the line color that you want to use in the visual theme, for example, #000000. Depending on the third-party add-on, this field can be optional or required.
98+
99+
.Additional resources
100+
* 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#assembly-third-party-plugins[Third-party plugins in {product}]

0 commit comments

Comments
 (0)