Skip to content

Commit 9b5f2ca

Browse files
linfrazelinfraze
committed
RHIDP-5422: Draft 'create' proc
1 parent 465aa2d commit 9b5f2ca

File tree

1 file changed

+163
-6
lines changed

1 file changed

+163
-6
lines changed

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

Lines changed: 163 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,171 @@
66
[id="proc-techdocs-addon-create_{context}"]
77
== Creating a TechDocs add-on
88

9-
You can create your own third-party TechDocs add-on for your {product} instance as a front-end dynamic plugin.
9+
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.
10+
11+
A TechDocs add-on is a react component that is imported from a front-end plugin. If you do not have an existing plugin for your TechDocs add-on, you can create a new plugin by configuring the default front-end plugin files in the `backstage/community-plugins` repository. After you create a new front-end plugin and a new TechDocs add-on, you can use the new plugin to import the new TechDocs add-on into your {product} instance.
12+
13+
The folder structure of a new plugin looks similar to the following example:
14+
[source,json,subs="+attributes,+quotes"]
15+
----
16+
_<new_plugin_for_techdocs_add-on>_/
17+
dev/
18+
index.ts
19+
node_modules/
20+
src/
21+
components/
22+
_<new_techdocs_add-on_component>_/
23+
_<new_techdocs_add-on_component>_.test.tsx
24+
_<new_techdocs_add-on_component>_.tsx
25+
index.ts
26+
_<new_techdocs_add-on_fetch-component>_/
27+
_<new_techdocs_add-on_fetch-component>_.test.tsx
28+
_<new_techdocs_add-on_fetch-component>_.tsx
29+
index.ts
30+
index.ts
31+
plugin.test.ts
32+
plugin.ts
33+
routes.ts
34+
setupTests.ts
35+
.eslintrc.js
36+
package.json
37+
README.md
38+
----
1039

11-
////
1240
.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.
41+
* The `yarn` package manager is installed.
42+
* Docker v3.2.0 or later or Podman v3.2.0 or later is installed and running.
1743
1844
.Procedure
45+
. In the terminal, navigate to the root folder of your {product} instance.
46+
. To create a new front-end plugin, run the following command:
47+
+
48+
[source,terminal,subs="+attributes,+quotes"]
49+
----
50+
yarn new
51+
----
52+
.Example output
53+
+
54+
[source,terminal,subs="+quotes"]
55+
----
56+
? What do you want to create? plugin - A new frontend plugin
57+
? Enter the ID of the plugin [required]
58+
----
59+
+
60+
. In the terminal prompt, type a name for the new plugin. For example:
61+
+
62+
[source,terminal,subs="+attributes,+quotes"]
63+
----
64+
? Enter the ID of the plugin [required] _<new_plugin_for_techdocs_add-on>_
65+
----
66+
+
67+
.Example output
68+
+
69+
[source,terminal,subs="+attributes,+quotes"]
70+
----
71+
Successfully created plugin
72+
----
73+
+
74+
[NOTE]
75+
====
76+
Running the `yarn new` command automatically generates a sub-directory with
77+
====
78+
+
79+
.Result
80+
In the `plugins` directory, there is an automatically generated sub-directory with the same name that you gave to your plugin. This plugin directory contains all of the files that you need to configure to create your new plugin.
81+
+
82+
. In the terminal, navigate to your new plugin directory. For example:
83+
+
84+
[source,terminal,subs="+attributes,+quotes"]
85+
----
86+
cd plugins/_<new_techdocs_add-on_directory>_
87+
----
88+
. Add the`@backstage/plugin-techdocs-react` package to get frontend utilities for TechDocs add-ons. For example:
89+
+
90+
[source,terminal,subs="+attributes,+quotes"]
91+
----
92+
yarn add @backstage/plugin-techdocs-react
93+
----
94+
. 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.
95+
. In the `plugins.ts` file, add the following code:
96+
+
97+
[source,java,subs="+attributes,+quotes"]
98+
----
99+
import { createPlugin } from '@backstage/core-plugin-api';
100+
import { createTechDocsAddonExtension } from '@backstage/plugin-techdocs-react';
101+
102+
export const _<new_plugin_for_techdocs_add-on>_ = createPlugin({
103+
id: '_<new_techdocs_add-on>_',
104+
});
105+
106+
/*
107+
*
108+
* @public
109+
*/
110+
export const _<new_techdocs_add-on>_ = _<new_plugin_for_techdocs_add-on>_.provide(
111+
createTechDocsAddonExtension<_<new_techdocs_addon_props>_>({
112+
name: '_<new_techdocs_add-on>_',
113+
location: TechDocsAddonLocations.Content,
114+
component: _<new_techdocs_add-on_component>_,
115+
}),
116+
);
117+
----
118+
+
119+
where
120+
121+
_<new_plugin_for_techdocs_add-on>_ :: Specifies the new plugin that you use to import the TechDocs add-on to your {product} instance.
122+
_<new_techdocs_add-on>_ :: Specifies the custom TechDocs add-on that you want to create.
123+
_<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.
124+
. In the `plugins.ts` file, import you new TechDocs add-on component.
125+
_<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.
126+
. In the `index.ts` file, export the custom TechDocs add-on that you want to create by adding the following code:
127+
+
128+
[source,java,subs="+attributes,+quotes"]
129+
----
130+
export { _<new_plugin_for_techdocs_add-on>_, _<new_techdocs_add-on>_ } from './plugin';
131+
----
132+
. Create a new `_<new_techdocs_add-on>_.tsx` file and add the code for your new TechDocs add-on component.
133+
+
134+
////
135+
[source,java,subs="+attributes,+quotes"]
136+
----
137+
can add example code for this file, if helpful
138+
can also mention a template that the user can configure, if there is one
139+
----
19140
////
141+
. Create a new `index.tsx` file and use it to export your new TechDocs add-on component by adding the following code:
142+
+
143+
[source,java,subs="+attributes,+quotes"]
144+
----
145+
export { _<new_techdocs_add-on>_, type _<new_techdocs_addon_props>_} from './_<new_techdocs_add-on_directory>_'
146+
----
147+
+
148+
where
149+
150+
_<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.
151+
. In the `plugins.ts` file, import you new TechDocs add-on component.
152+
. Navigate to `packages/app/src/components/catalog/EntityPage.tsx` and your new TechDocs add-on. For example:
153+
+
154+
[source,java,subs="+attributes,+quotes"]
155+
----
156+
...
157+
const techdocsContent = (
158+
<EntityTechdocsContent>
159+
<TechDocsAddons>
160+
<ReportIssue />
161+
<_<new_techdocs_add-on>_ />
162+
</TechDocsAddons>
163+
</EntityTechdocsContent>
164+
);
165+
...
166+
----
167+
168+
.Verification
169+
. In the terminal, navigate to the `rbac` directory.
170+
. To start your new TechDocs add-on, run the following command:
171+
+
172+
[source,terminal,subs="+attributes,+quotes"]
173+
----
174+
yarn dev
175+
----
176+
. From the TechDocs plugin in your {product} instance, confirm that your new add-on is working as expected.

0 commit comments

Comments
 (0)