Finish TechDocs migration to composability API.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

Author: iamEAP

.changeset/catalog-compose-my-techdocs.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-catalog': patch
+---
+
+The entity `<AboutCard />` now uses an external route ref to link to TechDocs
+sites. This external route must now be bound in order for the "View TechDocs"
+link to continue working. See the [create-app changelog][cacl] for details.
+
+[cacl]: https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md

.changeset/create-incerteza-desafinado-tomara.md

@@ -0,0 +1,28 @@
+---
+'@backstage/create-app': patch
+---
+
+Wire up TechDocs, which now relies on the composability API for routing.
+
+First, ensure you've mounted `<TechDocsReaderPage />`. If you already updated
+to use the composable `<TechDocsIndexPage />` (see below), no action is
+necessary. Otherwise, update your `App.tsx` so that `<TechDocsReaderPage />` is
+mounted:
+
+```diff
+     <Route path="/docs" element={<TechdocsPage />} />
++    <Route
++      path="/docs/:namespace/:kind/:name/*"
++      element={<TechDocsReaderPage />}
++    />
+```
+
+Next, ensure links from the Catalog Entity Page to its TechDocs site are bound:
+
+```diff
+  bindRoutes({ bind }) {
+    bind(catalogPlugin.externalRoutes, {
+      createComponent: scaffolderPlugin.routes.root,
++     viewTechDoc: techdocsPlugin.routes.docRoot,
+    });
+```

.changeset/techdocs-jobim-gilberto-moraes.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-techdocs': minor
+---
+
+The TechDocs plugin has completed the migration to the Composability API. In
+order to update to this version, please ensure you've made all necessary
+changes to your `App.tsx` file as outlined in the [create-app changelog][cacl].
+
+[cacl]: https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md

packages/app/src/App.tsx

@@ -55,6 +55,7 @@ import { TechRadarPage } from '@backstage/plugin-tech-radar';
 import {
   DefaultTechDocsHome,
   TechDocsIndexPage,
+  techdocsPlugin,
   TechDocsReaderPage,
 } from '@backstage/plugin-techdocs';
 import { UserSettingsPage } from '@backstage/plugin-user-settings';
@@ -93,6 +94,7 @@ const app = createApp({
   bindRoutes({ bind }) {
     bind(catalogPlugin.externalRoutes, {
       createComponent: scaffolderPlugin.routes.root,
+      viewTechDoc: techdocsPlugin.routes.docRoot,
     });
     bind(apiDocsPlugin.externalRoutes, {
       createComponent: scaffolderPlugin.routes.root,

packages/create-app/templates/default-app/packages/app/src/App.tsx

@@ -16,6 +16,7 @@ import { TechRadarPage } from '@backstage/plugin-tech-radar';
 import {
   DefaultTechDocsHome,
   TechDocsIndexPage,
+  techdocsPlugin,
   TechDocsReaderPage,
 } from '@backstage/plugin-techdocs';
 import { UserSettingsPage } from '@backstage/plugin-user-settings';
@@ -31,6 +32,7 @@ const app = createApp({
   bindRoutes({ bind }) {
     bind(catalogPlugin.externalRoutes, {
       createComponent: scaffolderPlugin.routes.root,
+      viewTechDoc: techdocsPlugin.routes.docRoot,
     });
     bind(apiDocsPlugin.externalRoutes, {
       createComponent: scaffolderPlugin.routes.root,

plugins/catalog/api-report.md

@@ -128,6 +128,14 @@ const catalogPlugin: BackstagePlugin<
   },
   {
     createComponent: ExternalRouteRef<undefined, true>;
+    viewTechDoc: ExternalRouteRef<
+      {
+        name: string;
+        kind: string;
+        namespace: string;
+      },
+      true
+    >;
   }
 >;
 export { catalogPlugin };
@@ -399,7 +407,7 @@ export const Router: ({
 // src/components/EntityLayout/EntityLayout.d.ts:43:5 - (ae-forgotten-export) The symbol "EntityLayoutProps" needs to be exported by the entry point index.d.ts
 // src/components/EntityLayout/EntityLayout.d.ts:44:5 - (ae-forgotten-export) The symbol "SubRoute" needs to be exported by the entry point index.d.ts
 // src/components/EntityPageLayout/EntityPageLayout.d.ts:17:5 - (ae-forgotten-export) The symbol "EntityPageLayoutProps" needs to be exported by the entry point index.d.ts
-// src/plugin.d.ts:17:5 - (ae-forgotten-export) The symbol "ColumnBreakpoints" needs to be exported by the entry point index.d.ts
+// src/plugin.d.ts:22:5 - (ae-forgotten-export) The symbol "ColumnBreakpoints" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 ```

plugins/catalog/src/components/AboutCard/AboutCard.test.tsx

@@ -29,6 +29,7 @@ import {
   ApiRegistry,
   ConfigReader,
 } from '@backstage/core-app-api';
+import { viewTechDocRouteRef } from '../../routes';
 
 describe('<AboutCard />', () => {
   it('renders info', async () => {
@@ -203,4 +204,138 @@ describe('<AboutCard />', () => {
     );
     expect(getByText('View Source').closest('a')).not.toHaveAttribute('href');
   });
+
+  it('renders techdocs link', async () => {
+    const entity = {
+      apiVersion: 'v1',
+      kind: 'Component',
+      metadata: {
+        name: 'software',
+        annotations: {
+          'backstage.io/techdocs-ref': './',
+        },
+      },
+      spec: {
+        owner: 'guest',
+        type: 'service',
+        lifecycle: 'production',
+      },
+    };
+    const apis = ApiRegistry.with(
+      scmIntegrationsApiRef,
+      ScmIntegrationsApi.fromConfig(
+        new ConfigReader({
+          integrations: {
+            github: [
+              {
+                host: 'github.com',
+                token: '...',
+              },
+            ],
+          },
+        }),
+      ),
+    );
+
+    const { getByText } = await renderInTestApp(
+      <ApiProvider apis={apis}>
+        <EntityProvider entity={entity}>
+          <AboutCard />
+        </EntityProvider>
+      </ApiProvider>,
+      {
+        mountedRoutes: {
+          '/docs/:namespace/:kind/:name': viewTechDocRouteRef,
+        },
+      },
+    );
+
+    expect(getByText('View TechDocs').closest('a')).toHaveAttribute(
+      'href',
+      '/docs/default/Component/software',
+    );
+  });
+
+  it('renders disabled techdocs link when no docs exist', async () => {
+    const entity = {
+      apiVersion: 'v1',
+      kind: 'Component',
+      metadata: {
+        name: 'software',
+      },
+      spec: {
+        owner: 'guest',
+        type: 'service',
+        lifecycle: 'production',
+      },
+    };
+    const apis = ApiRegistry.with(
+      scmIntegrationsApiRef,
+      ScmIntegrationsApi.fromConfig(
+        new ConfigReader({
+          integrations: {
+            github: [
+              {
+                host: 'github.com',
+                token: '...',
+              },
+            ],
+          },
+        }),
+      ),
+    );
+
+    const { getByText } = await renderInTestApp(
+      <ApiProvider apis={apis}>
+        <EntityProvider entity={entity}>
+          <AboutCard />
+        </EntityProvider>
+      </ApiProvider>,
+    );
+
+    expect(getByText('View TechDocs').closest('a')).not.toHaveAttribute('href');
+  });
+
+  it('renders disbaled techdocs link when route is not bound', async () => {
+    const entity = {
+      apiVersion: 'v1',
+      kind: 'Component',
+      metadata: {
+        name: 'software',
+        annotations: {
+          'backstage.io/techdocs-ref': './',
+        },
+      },
+      spec: {
+        owner: 'guest',
+        type: 'service',
+        lifecycle: 'production',
+      },
+    };
+    const apis = ApiRegistry.with(
+      scmIntegrationsApiRef,
+      ScmIntegrationsApi.fromConfig(
+        new ConfigReader({
+          integrations: {
+            github: [
+              {
+                host: 'github.com',
+                token: '...',
+              },
+            ],
+          },
+        }),
+      ),
+    );
+
+    const { getByText } = await renderInTestApp(
+      <ApiProvider apis={apis}>
+        <EntityProvider entity={entity}>
+          <AboutCard />
+        </EntityProvider>
+      </ApiProvider>,
+    );
+
+    expect(getByText('View TechDocs').closest('a')).not.toHaveAttribute('href');
+  });
 });

plugins/catalog/src/components/AboutCard/AboutCard.tsx

@@ -49,7 +49,8 @@ import {
   IconLinkVerticalProps,
   InfoCardVariants,
 } from '@backstage/core-components';
-import { useApi } from '@backstage/core-plugin-api';
+import { useApi, useRouteRef } from '@backstage/core-plugin-api';
+import { viewTechDocRouteRef } from '../../routes';
 
 const useStyles = makeStyles({
   gridItemCard: {
@@ -81,6 +82,8 @@ export function AboutCard({ variant }: AboutCardProps) {
   const classes = useStyles();
   const { entity } = useEntity();
   const scmIntegrationsApi = useApi(scmIntegrationsApiRef);
+  const viewTechdocLink = useRouteRef(viewTechDocRouteRef);
+
   const entitySourceLocation = getEntitySourceLocation(
     entity,
     scmIntegrationsApi,
@@ -105,11 +108,17 @@ export function AboutCard({ variant }: AboutCardProps) {
   };
   const viewInTechDocs: IconLinkVerticalProps = {
     label: 'View TechDocs',
-    disabled: !entity.metadata.annotations?.['backstage.io/techdocs-ref'],
+    disabled:
+      !entity.metadata.annotations?.['backstage.io/techdocs-ref'] ||
+      !viewTechdocLink,
     icon: <DocsIcon />,
-    href: `/docs/${entity.metadata.namespace || ENTITY_DEFAULT_NAMESPACE}/${
-      entity.kind
-    }/${entity.metadata.name}`,
+    href:
+      viewTechdocLink &&
+      viewTechdocLink({
+        namespace: entity.metadata.namespace || ENTITY_DEFAULT_NAMESPACE,
+        kind: entity.kind,
+        name: entity.metadata.name,
+      }),
   };
   const viewApi: IconLinkVerticalProps = {
     title: hasApis ? '' : 'No APIs available',

plugins/catalog/src/plugin.ts

@@ -21,7 +21,7 @@ import {
   entityRouteRef,
 } from '@backstage/plugin-catalog-react';
 import { CatalogClientWrapper } from './CatalogClientWrapper';
-import { createComponentRouteRef } from './routes';
+import { createComponentRouteRef, viewTechDocRouteRef } from './routes';
 import {
   createApiFactory,
   createComponentExtension,
@@ -50,6 +50,7 @@ export const catalogPlugin = createPlugin({
   },
   externalRoutes: {
     createComponent: createComponentRouteRef,
+    viewTechDoc: viewTechDocRouteRef,
   },
 });
 

plugins/catalog/src/routes.ts

@@ -20,3 +20,9 @@ export const createComponentRouteRef = createExternalRouteRef({
   id: 'create-component',
   optional: true,
 });
+
+export const viewTechDocRouteRef = createExternalRouteRef({
+  id: 'view-techdoc',
+  optional: true,
+  params: ['namespace', 'kind', 'name'],
+});