Skip to content

Commit 78ff498

Browse files
linfrazelinfraze
committed
RHIDP-5422: Draft 'create' proc
1 parent bca813a commit 78ff498

File tree

1 file changed

+152
-6
lines changed

1 file changed

+152
-6
lines changed

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

Lines changed: 152 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,160 @@
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+
+
15+
[source,json,subs="+attributes,+quotes"]
16+
----
17+
_<new_plugin_for_techdocs_add-on>_/
18+
dev/
19+
index.ts
20+
node_modules/
21+
src/
22+
components/
23+
_<new_techdocs_add-on_component>_/
24+
_<new_techdocs_add-on_component>_.test.tsx
25+
_<new_techdocs_add-on_component>_.tsx
26+
index.ts
27+
_<new_techdocs_add-on_fetch-component>_/
28+
_<new_techdocs_add-on_fetch-component>_.test.tsx
29+
_<new_techdocs_add-on_fetch-component>_.tsx
30+
index.ts
31+
index.ts
32+
plugin.test.ts
33+
plugin.ts
34+
routes.ts
35+
setupTests.ts
36+
.eslintrc.js
37+
package.json
38+
README.md
39+
----
1040

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

0 commit comments

Comments
 (0)