feat(app): dynamic Techdocs addons #2238

dzemanov · 2025-01-23T08:38:32Z

Description

This change adds support for dynamically loading Techdocs Addons. It creates a wrapper for techdocs-module-addons-contrib which contains techdocs extensions:

LightBox
ReportIssue
TextSize
ExpandableNavigation

A plugin can export a Techdocs extension like:

export const TextSize = techdocsModuleAddonsContribPlugin.provide(
  createTechDocsAddonExtension({
    name: 'TextSize',
    location: TechDocsAddonLocations.Settings,
    component: TextSizeAddon,
  }),
);

Use new configuration option:

frontend:
  backstage.plugin-techdocs-module-addons-contrib:
    techdocsAddons:
      - importName: TextSize

Which issue(s) does this PR fix

Fixes RHIDP-5499

PR acceptance criteria

Please make sure that the following steps are complete:

GitHub Actions are completed and successful
Unit Tests are updated and passing
E2E Tests are updated and passing
Documentation is updated if necessary (requirement for new features)
Add a screenshot if the change is UX/UI related

How to test changes / Special notes to the reviewer

You can add to app-config.yaml this config:

techdocs:
  builder: 'local'

dynamicPlugins:
  rootDirectory: dynamic-plugins-root
  frontend:
    backstage.plugin-techdocs:
      routeBindings:
        targets:
          - importName: techdocsPlugin
        bindings:
          - bindTarget: catalogPlugin.externalRoutes
            bindMap:
              viewTechDoc: techdocsPlugin.routes.docRoot
          - bindTarget: scaffolderPlugin.externalRoutes
            bindMap:
              viewTechDoc: techdocsPlugin.routes.docRoot
      dynamicRoutes:
        - path: /docs
          importName: TechDocsIndexPage
          menuItem:
            icon: docs
            text: Docs
        - path: /docs/:namespace/:kind/:name/*
          importName: TechDocsReaderPage
      mountPoints:
        - mountPoint: entity.page.docs/cards
          importName: EntityTechdocsContent
          config:
            layout:
              gridColumn: "1 / -1"
            if:
              allOf:
                - isTechDocsAvailable
        - mountPoint: search.page.results
          importName: TechDocsSearchResultListItem
        - mountPoint: search.page.filters
          importName: TechdocsSearchFilter
        - mountPoint: search.page.types
          importName: techdocsSearchType
          config:
            props:
              name: Documentation
              icon: docs

    backstage.plugin-techdocs-module-addons-contrib:
      techdocsAddons:
        - importName: TextSize
        - importName: LightBox
        - importName: ReportIssue
        - importName: ExpandableNavigation

2025-01-24.12-39-47.mp4

github-actions · 2025-01-23T10:25:41Z

The image is available at:

github-actions · 2025-01-23T12:06:20Z

The image is available at:

github-actions · 2025-01-23T14:52:32Z

The image is available at:

dzemanov · 2025-01-23T15:02:08Z

/cc @gashcrumb can you take a look if this approach is alright? There is a bug with ReportIssue and maybe ExpandableNavigation but otherwise addons should work correctly. TextSize addon adds settings at the docs top which can change the size of text, LightBox enables to view pictures in overlay.

dzemanov · 2025-01-23T17:52:21Z

ReportIssue bug is fixed.
Not sure if I can use importName for the filtering for TechDocs dynamic components or is there something better / safer to use.

github-actions · 2025-01-23T18:23:10Z

The image is available at:

github-actions · 2025-01-27T12:23:54Z

The image is available at:

dzemanov · 2025-01-27T12:51:57Z

Removed previously added "@backstage/plugin-techdocs-react" dependency to app and removed importName filtering.
Introduced option of passing dynamicConfig to staticJSXContent.

github-actions · 2025-01-27T13:21:36Z

The image is available at:

dzemanov · 2025-02-03T15:28:08Z

/cc @davidfestal
/cc @kadel
/cc @christoph-jerolimov

Signed-off-by: Dominika Zemanovicova <[email protected]>

dzemanov · 2025-02-10T11:14:52Z

/retest

github-actions · 2025-02-10T11:45:19Z

The image is available at:

christoph-jerolimov · 2025-02-10T13:51:23Z

For some reason I didn't understand yet, the latest version didn't worked on a cluster.

Absolutely no dynamic plugin is loaded. We need to check if its this PR or a general issue. But to be save I mark this as

/hold

PatAKnight · 2025-02-10T17:18:21Z

@christoph-jerolimov I was able to make it work on a cluster. Wonder if there was some other issue that was popping up for you?

gashcrumb · 2025-02-10T18:36:07Z

app-config.dynamic-plugins.yaml

@@ -471,6 +471,9 @@ dynamicPlugins:
            props:
              name: Documentation
              icon: docs
+    backstage.plugin-techdocs-module-addons-contrib:


I've seen both a . and a - used as the org/package separator. I think we should consider that inconsistency here confuses users, and I wonder if we shouldn't just stick with using -. I'll have a 2nd comment on this in the plugin's scalprum config :-)

I would maybe let it be this way for now, but we can do a following bulk update for all the plugins that have it this way.

yep, I don't know if there's any formal convention here so maybe one needs to be established.

gashcrumb · 2025-02-10T18:39:04Z

dynamic-plugins/wrappers/backstage-plugin-techdocs-module-addons-contrib/package.json

+    "dist",
+    "dist-scalprum"
+  ],
+  "scalprum": {


Is it necessary to add this config? Without it I believe the scalprum name would be backstage-plugin-techdocs-module-addons-contrib which I think actually is less confusing as it's taken from the package.json name. I just worry these slight differences here and there confuse users, I recently had a conversation around this field, the package name and what is used in the configuration. Maybe not something to fix right now but to consider very soon.

Yeah, not necessary. I have seen both versions being used, it would be great to unify this.

gashcrumb

I did a quick local test using the PR image and could see the add-ons installed, very nice! A couple comments but nothing that needs to be addressed in this PR.

christoph-jerolimov · 2025-02-10T22:06:26Z

I've tested it now again on a new cluster and couldn't reproduce my earlier issue. 🤷‍♂️

/lgtm
/unhold

openshift-ci · 2025-02-10T22:06:37Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: christoph-jerolimov, gashcrumb

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [christoph-jerolimov,gashcrumb]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

dzemanov marked this pull request as draft January 23, 2025 08:38

openshift-ci bot requested review from its-mitesh-kumar and kim-tsao January 23, 2025 08:38

openshift-ci bot added the do-not-merge/work-in-progress label Jan 23, 2025

dzemanov changed the title ~~Techdocs addons~~ feat(app): dynamic Techdocs addons Jan 23, 2025

dzemanov force-pushed the techdocs-addons branch 4 times, most recently from 5187cf2 to fdd354b Compare January 23, 2025 09:21

dzemanov force-pushed the techdocs-addons branch from 88c2f2a to c3117d1 Compare January 23, 2025 17:47

dzemanov marked this pull request as ready for review January 23, 2025 17:59

openshift-ci bot removed the do-not-merge/work-in-progress label Jan 23, 2025

openshift-ci bot requested a review from coreydaley January 23, 2025 17:59

dzemanov force-pushed the techdocs-addons branch from c3117d1 to 0abe50e Compare January 24, 2025 09:09

openshift-merge-robot added the needs-rebase label Jan 27, 2025

dzemanov force-pushed the techdocs-addons branch from ed2d797 to 6a442d3 Compare January 27, 2025 11:13

openshift-merge-robot removed the needs-rebase label Jan 27, 2025

openshift-ci bot requested review from christoph-jerolimov, davidfestal and kadel February 3, 2025 15:28

dzemanov added 15 commits February 10, 2025 12:09

Fix ReportIssue wrapper not being used

1a81e9c

Signed-off-by: Dominika Zemanovicova <[email protected]>

Update docs

ba2a8d9

Signed-off-by: Dominika Zemanovicova <[email protected]>

Use techdocsAddons keywords

e5be8c1

Signed-off-by: Dominika Zemanovicova <[email protected]>

Add default config

ae25993

Signed-off-by: Dominika Zemanovicova <[email protected]>

Introduce staticJSXContent as function

49e1c74

Signed-off-by: Dominika Zemanovicova <[email protected]>

StaticJSXContent gets dynamicConfig as argument

b451675

Signed-off-by: Dominika Zemanovicova <[email protected]>

Update dependencies

da021e6

Signed-off-by: Dominika Zemanovicova <[email protected]>

Fix url

1179847

Signed-off-by: Dominika Zemanovicova <[email protected]>

Remove importName changes

f94bbc3

Signed-off-by: Dominika Zemanovicova <[email protected]>

Update docs information about staticJSXContent

84ccc28

Signed-off-by: Dominika Zemanovicova <[email protected]>

Remove not needed rename

5d5db04

Signed-off-by: Dominika Zemanovicova <[email protected]>

Update addons-contrib deps

808d713

Signed-off-by: Dominika Zemanovicova <[email protected]>

Update janus mention

57c94e1

Signed-off-by: Dominika Zemanovicova <[email protected]>

Update dependencies

b82b4b3

Signed-off-by: Dominika Zemanovicova <[email protected]>

Add ReportIssue as default

47fabd8

Signed-off-by: Dominika Zemanovicova <[email protected]>

dzemanov force-pushed the techdocs-addons branch from daaba49 to 47fabd8 Compare February 10, 2025 11:10

openshift-ci bot added the do-not-merge/hold label Feb 10, 2025

gashcrumb reviewed Feb 10, 2025

View reviewed changes

gashcrumb approved these changes Feb 10, 2025

View reviewed changes

openshift-ci bot removed the do-not-merge/hold label Feb 10, 2025

openshift-ci bot assigned christoph-jerolimov Feb 10, 2025

openshift-ci bot added the lgtm label Feb 10, 2025

openshift-merge-bot bot merged commit 56cbf89 into redhat-developer:main Feb 10, 2025
15 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(app): dynamic Techdocs addons #2238

feat(app): dynamic Techdocs addons #2238

dzemanov commented Jan 23, 2025 •

edited

Loading

github-actions bot commented Jan 23, 2025

github-actions bot commented Jan 23, 2025

github-actions bot commented Jan 23, 2025

dzemanov commented Jan 23, 2025

dzemanov commented Jan 23, 2025

github-actions bot commented Jan 23, 2025

github-actions bot commented Jan 27, 2025

dzemanov commented Jan 27, 2025

github-actions bot commented Jan 27, 2025

dzemanov commented Feb 3, 2025

dzemanov commented Feb 10, 2025

github-actions bot commented Feb 10, 2025

christoph-jerolimov commented Feb 10, 2025

PatAKnight commented Feb 10, 2025

gashcrumb Feb 10, 2025

dzemanov Feb 10, 2025

gashcrumb Feb 10, 2025

gashcrumb Feb 10, 2025 •

edited

Loading

dzemanov Feb 10, 2025

gashcrumb left a comment

christoph-jerolimov commented Feb 10, 2025

openshift-ci bot commented Feb 10, 2025

feat(app): dynamic Techdocs addons #2238

feat(app): dynamic Techdocs addons #2238

Conversation

dzemanov commented Jan 23, 2025 • edited Loading

Description

Which issue(s) does this PR fix

PR acceptance criteria

How to test changes / Special notes to the reviewer

github-actions bot commented Jan 23, 2025

github-actions bot commented Jan 23, 2025

github-actions bot commented Jan 23, 2025

dzemanov commented Jan 23, 2025

dzemanov commented Jan 23, 2025

github-actions bot commented Jan 23, 2025

github-actions bot commented Jan 27, 2025

dzemanov commented Jan 27, 2025

github-actions bot commented Jan 27, 2025

dzemanov commented Feb 3, 2025

dzemanov commented Feb 10, 2025

github-actions bot commented Feb 10, 2025

christoph-jerolimov commented Feb 10, 2025

PatAKnight commented Feb 10, 2025

gashcrumb Feb 10, 2025

Choose a reason for hiding this comment

dzemanov Feb 10, 2025

Choose a reason for hiding this comment

gashcrumb Feb 10, 2025

Choose a reason for hiding this comment

gashcrumb Feb 10, 2025 • edited Loading

Choose a reason for hiding this comment

dzemanov Feb 10, 2025

Choose a reason for hiding this comment

gashcrumb left a comment

Choose a reason for hiding this comment

christoph-jerolimov commented Feb 10, 2025

openshift-ci bot commented Feb 10, 2025

dzemanov commented Jan 23, 2025 •

edited

Loading

gashcrumb Feb 10, 2025 •

edited

Loading