From 071c1c1de0a7118482357a36a5966a7b537593ed Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 22 Feb 2022 15:41:04 +0100 Subject: [PATCH] api report clean ups Signed-off-by: Emma Indal --- plugins/techdocs/api-report.md | 367 ++++++++---------- plugins/techdocs/src/Router.tsx | 21 +- .../home/components/DefaultTechDocsHome.tsx | 3 +- .../home/components/LegacyTechDocsHome.tsx | 3 + .../home/components/TechDocsCustomHome.tsx | 24 +- .../home/components/TechDocsPageWrapper.tsx | 15 +- .../src/home/components/TechDocsPicker.tsx | 5 + plugins/techdocs/src/plugin.ts | 72 ++-- .../reader/components/LegacyTechDocsPage.tsx | 7 +- .../techdocs/src/reader/components/Reader.tsx | 41 +- plugins/techdocs/src/types.ts | 10 + 11 files changed, 311 insertions(+), 257 deletions(-) diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index 7d554a293c..3b953556c4 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -22,50 +22,7 @@ import { TableColumn } from '@backstage/core-components'; import { TableProps } from '@backstage/core-components'; import { UserListFilterKind } from '@backstage/plugin-catalog-react'; -// Warning: (ae-missing-release-tag) "createCopyDocsUrlAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createCopyDocsUrlAction(copyToClipboard: Function): ( - row: DocsTableRow, -) => { - icon: () => JSX.Element; - tooltip: string; - onClick: () => any; -}; - -// Warning: (ae-missing-release-tag) "createNameColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createNameColumn(): TableColumn; - -// Warning: (ae-missing-release-tag) "createOwnerColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createOwnerColumn(): TableColumn; - -// Warning: (ae-missing-release-tag) "createStarEntityAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createStarEntityAction( - isStarredEntity: Function, - toggleStarredEntity: Function, -): ({ entity }: DocsTableRow) => { - cellStyle: { - paddingLeft: string; - }; - icon: () => JSX.Element; - tooltip: string; - onClick: () => any; -}; - -// Warning: (ae-missing-release-tag) "createTypeColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -function createTypeColumn(): TableColumn; - -// Warning: (ae-missing-release-tag) "DefaultTechDocsHome" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const DefaultTechDocsHome: ({ initialFilter, columns, @@ -73,49 +30,6 @@ export const DefaultTechDocsHome: ({ }: { initialFilter?: UserListFilterKind | undefined; columns?: TableColumn[] | undefined; - actions?: TableProps['actions']; -}) => JSX.Element; - -// Warning: (ae-missing-release-tag) "DocsCardGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const DocsCardGrid: ({ - entities, -}: { - entities: Entity[] | undefined; -}) => JSX.Element | null; - -// Warning: (ae-missing-release-tag) "DocsResultListItem" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const DocsResultListItem: ({ - result, - lineClamp, - asListItem, - asLink, - title, -}: { - result: any; - lineClamp?: number | undefined; - asListItem?: boolean | undefined; - asLink?: boolean | undefined; - title?: string | undefined; -}) => JSX.Element; - -// Warning: (ae-missing-release-tag) "DocsTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const DocsTable: ({ - entities, - title, - loading, - columns, - actions, -}: { - entities: Entity[] | undefined; - title?: string | undefined; - loading?: boolean | undefined; - columns?: TableColumn[] | undefined; actions?: | ( | Action @@ -126,11 +40,33 @@ export const DocsTable: ({ | ((rowData: DocsTableRow) => Action) )[] | undefined; +}) => JSX.Element; + +// @public +export const DocsCardGrid: ({ + entities, +}: { + entities: Entity[] | undefined; }) => JSX.Element | null; -// Warning: (ae-missing-release-tag) "DocsTableRow" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public @deprecated (undocumented) +export const DocsResultListItem: ( + props: TechDocsSearchResultListItemProps, +) => JSX.Element; + +// @public +export const DocsTable: (props: DocsTableProps) => JSX.Element | null; + +// @public +export type DocsTableProps = { + entities: Entity[] | undefined; + title?: string | undefined; + loading?: boolean | undefined; + columns?: TableColumn[]; + actions?: TableProps['actions']; +}; + +// @public export type DocsTableRow = { entity: Entity; resolved: { @@ -140,74 +76,80 @@ export type DocsTableRow = { }; }; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "EmbeddedDocsRouter" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const EmbeddedDocsRouter: (_props: Props_2) => JSX.Element; +// @public +export const EmbeddedDocsRouter: () => JSX.Element; -// Warning: (ae-missing-release-tag) "EntityListDocsGrid" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityListDocsGrid: () => JSX.Element; -// Warning: (ae-missing-release-tag) "EntityListDocsTable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const EntityListDocsTable: { - ({ - columns, - actions, - }: { - columns?: TableColumn[] | undefined; - actions?: TableProps['actions']; - }): JSX.Element; + (props: EntityListDocsTableProps): JSX.Element; columns: typeof columnFactories; actions: typeof actionFactories; }; -// Warning: (ae-missing-release-tag) "EntityTechdocsContent" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const EntityTechdocsContent: (_props: {}) => JSX.Element; +// @public +export type EntityListDocsTableProps = { + columns?: TableColumn[]; + actions?: TableProps['actions']; +}; -// Warning: (ae-missing-release-tag) "isTechDocsAvailable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export const EntityTechdocsContent: () => JSX.Element; + +// @public export const isTechDocsAvailable: (entity: Entity) => boolean; -// Warning: (ae-missing-release-tag) "PanelType" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export interface PanelConfig { + // (undocumented) + description: string; + // (undocumented) + filterPredicate: ((entity: Entity) => boolean) | string; + // (undocumented) + panelCSS?: CSSProperties; + // (undocumented) + panelType: PanelType; + // (undocumented) + title: string; +} + +// @public export type PanelType = 'DocsCardGrid' | 'DocsTable'; -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "Reader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const Reader: ({ - entityRef, - onReady, - withSearch, -}: Props_3) => JSX.Element; +// @public +export const Reader: (props: ReaderProps) => JSX.Element; -// Warning: (ae-missing-release-tag) "Router" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type ReaderProps = { + entityRef: EntityName; + withSearch?: boolean; + onReady?: () => void; +}; + +// @public export const Router: () => JSX.Element; // @public export type SyncResult = 'cached' | 'updated'; +// @public +export interface TabConfig { + // (undocumented) + label: string; + // (undocumented) + panels: PanelConfig[]; +} + +// @public +export type TabsConfig = TabConfig[]; + // @public export interface TechDocsApi { getApiOrigin(): Promise; - // Warning: (ae-forgotten-export) The symbol "TechDocsEntityMetadata" needs to be exported by the entry point index.d.ts - // // (undocumented) getEntityMetadata(entityId: EntityName): Promise; - // Warning: (ae-forgotten-export) The symbol "TechDocsMetadata" needs to be exported by the entry point index.d.ts - // // (undocumented) getTechDocsMetadata(entityId: EntityName): Promise; } @@ -232,84 +174,61 @@ export class TechDocsClient implements TechDocsApi { getTechDocsMetadata(entityId: EntityName): Promise; } -// Warning: (ae-missing-release-tag) "TechDocsCustomHome" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const TechDocsCustomHome: ({ tabsConfig, }: { tabsConfig: TabsConfig; }) => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsIndexPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public +export type TechDocsEntityMetadata = Entity & { + locationMetadata?: LocationSpec; +}; + +// @public export const TechDocsIndexPage: () => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const TechDocsPage: ({ children }: TechDocsPageProps) => JSX.Element; +// @public +export type TechDocsMetadata = { + site_name: string; + site_description: string; +}; -// Warning: (ae-missing-release-tag) "TechdocsPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public @deprecated (undocumented) +export const TechDocsPage: (props: TechDocsReaderPageProps) => JSX.Element; + +// @public export const TechdocsPage: () => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsPageHeader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public @deprecated (undocumented) export const TechDocsPageHeader: ({ entityRef, entityMetadata, techDocsMetadata, children, -}: TechDocsPageHeaderProps) => JSX.Element; +}: TechDocsReaderPageHeaderProps) => JSX.Element; -// Warning: (ae-missing-release-tag) "TechDocsPageHeaderProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type TechDocsPageHeaderProps = PropsWithChildren<{ - entityRef: EntityName; - entityMetadata?: TechDocsEntityMetadata; - techDocsMetadata?: TechDocsMetadata; -}>; +// @public @deprecated (undocumented) +export type TechDocsPageHeaderProps = TechDocsReaderPageHeaderProps; -// Warning: (ae-missing-release-tag) "TechDocsPageProps" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type TechDocsPageProps = { - children?: TechDocsPageRenderFunction | React_2.ReactNode; +// @public @deprecated (undocumented) +export type TechDocsPageRenderFunction = TechDocsReaderPageRenderFunction; + +// @public +export const TechDocsPageWrapper: ( + props: TechDocsPageWrapperProps, +) => JSX.Element; + +// @public +export type TechDocsPageWrapperProps = { + children?: React_2.ReactNode; }; -// Warning: (ae-missing-release-tag) "TechDocsPageRenderFunction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export type TechDocsPageRenderFunction = ({ - techdocsMetadataValue, - entityMetadataValue, - entityRef, -}: { - techdocsMetadataValue?: TechDocsMetadata | undefined; - entityMetadataValue?: TechDocsEntityMetadata | undefined; - entityRef: EntityName; - onReady: () => void; -}) => JSX.Element; - -// Warning: (ae-forgotten-export) The symbol "Props" needs to be exported by the entry point index.d.ts -// Warning: (ae-missing-release-tag) "TechDocsPageWrapper" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const TechDocsPageWrapper: ({ children }: Props) => JSX.Element; - -// Warning: (ae-missing-release-tag) "TechDocsPicker" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export const TechDocsPicker: () => null; -// Warning: (ae-missing-release-tag) "techdocsPlugin" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public const techdocsPlugin: BackstagePlugin< { root: RouteRef; @@ -325,12 +244,65 @@ const techdocsPlugin: BackstagePlugin< export { techdocsPlugin as plugin }; export { techdocsPlugin }; -// Warning: (ae-missing-release-tag) "TechDocsReaderPage" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const TechDocsReaderPage: ({ +// @public +export const TechDocsReaderPage: ( + props: TechDocsReaderPageProps, +) => JSX.Element; + +// @public +export const TechDocsReaderPageHeader: ({ + entityRef, + entityMetadata, + techDocsMetadata, children, -}: TechDocsPageProps) => JSX.Element; +}: TechDocsReaderPageHeaderProps) => JSX.Element; + +// @public +export type TechDocsReaderPageHeaderProps = PropsWithChildren<{ + entityRef: EntityName; + entityMetadata?: TechDocsEntityMetadata; + techDocsMetadata?: TechDocsMetadata; +}>; + +// @public +export type TechDocsReaderPageProps = { + children?: TechDocsReaderPageRenderFunction | React_2.ReactNode; +}; + +// @public +export type TechDocsReaderPageRenderFunction = ({ + techdocsMetadataValue, + entityMetadataValue, + entityRef, +}: { + techdocsMetadataValue?: TechDocsMetadata | undefined; + entityMetadataValue?: TechDocsEntityMetadata | undefined; + entityRef: EntityName; + onReady: () => void; +}) => JSX.Element; + +// @public +export const TechDocsSearch: (props: TechDocsSearchProps) => JSX.Element; + +// @public +export type TechDocsSearchProps = { + entityId: EntityName; + debounceTime?: number; +}; + +// @public +export const TechDocsSearchResultListItem: ( + props: TechDocsSearchResultListItemProps, +) => JSX.Element; + +// @public +export type TechDocsSearchResultListItemProps = { + result: any; + lineClamp?: number; + asListItem?: boolean; + asLink?: boolean; + title?: string; +}; // @public export interface TechDocsStorageApi { @@ -392,7 +364,6 @@ export class TechDocsStorageClient implements TechDocsStorageApi { // Warnings were encountered during analysis: // -// src/home/components/EntityListDocsTable.d.ts:11:5 - (ae-forgotten-export) The symbol "columnFactories" needs to be exported by the entry point index.d.ts -// src/home/components/EntityListDocsTable.d.ts:12:5 - (ae-forgotten-export) The symbol "actionFactories" needs to be exported by the entry point index.d.ts -// src/plugin.d.ts:27:5 - (ae-forgotten-export) The symbol "TabsConfig" needs to be exported by the entry point index.d.ts +// src/home/components/Tables/EntityListDocsTable.d.ts:22:5 - (ae-forgotten-export) The symbol "columnFactories" needs to be exported by the entry point index.d.ts +// src/home/components/Tables/EntityListDocsTable.d.ts:23:5 - (ae-forgotten-export) The symbol "actionFactories" needs to be exported by the entry point index.d.ts ``` diff --git a/plugins/techdocs/src/Router.tsx b/plugins/techdocs/src/Router.tsx index 0ba69c021f..3a49f6edf9 100644 --- a/plugins/techdocs/src/Router.tsx +++ b/plugins/techdocs/src/Router.tsx @@ -19,15 +19,25 @@ import { Entity } from '@backstage/catalog-model'; import { useEntity } from '@backstage/plugin-catalog-react'; import { Route, Routes } from 'react-router-dom'; import { TechDocsIndexPage } from './home/components/TechDocsIndexPage'; -import { TechDocsPage as TechDocsReaderPage } from './reader/components/TechDocsPage'; +import { TechDocsReaderPage } from './reader/components/TechDocsReaderPage'; import { EntityPageDocs } from './EntityPageDocs'; import { MissingAnnotationEmptyState } from '@backstage/core-components'; const TECHDOCS_ANNOTATION = 'backstage.io/techdocs-ref'; +/** + * Helper that takes in entity and returns true/false if TechDocs is available for the entity + * + * @public + */ export const isTechDocsAvailable = (entity: Entity) => Boolean(entity?.metadata?.annotations?.[TECHDOCS_ANNOTATION]); +/** + * Responsible for registering routes for TechDocs, TechDocs Homepage and separate TechDocs page + * + * @public + */ export const Router = () => { return ( @@ -40,9 +50,12 @@ export const Router = () => { ); }; -type Props = {}; - -export const EmbeddedDocsRouter = (_props: Props) => { +/** + * Responsible for registering route to view docs on Entity page + * + * @public + */ +export const EmbeddedDocsRouter = () => { const { entity } = useEntity(); const projectId = entity.metadata.annotations?.[TECHDOCS_ANNOTATION]; diff --git a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx index ff4bf63724..af9fbb093d 100644 --- a/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx +++ b/plugins/techdocs/src/home/components/DefaultTechDocsHome.tsx @@ -34,10 +34,9 @@ import { UserListFilterKind, UserListPicker, } from '@backstage/plugin-catalog-react'; -import { EntityListDocsTable } from './EntityListDocsTable'; import { TechDocsPageWrapper } from './TechDocsPageWrapper'; import { TechDocsPicker } from './TechDocsPicker'; -import { DocsTableRow } from './types'; +import { DocsTableRow, EntityListDocsTable } from './Tables'; export const DefaultTechDocsHome = ({ initialFilter = 'all', diff --git a/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx b/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx index 34ea416026..536c2c80c8 100644 --- a/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx +++ b/plugins/techdocs/src/home/components/LegacyTechDocsHome.tsx @@ -17,6 +17,9 @@ import React from 'react'; import { PanelType, TechDocsCustomHome } from './TechDocsCustomHome'; +/** + * @deprecated Use {@link TechDocsCustomHome} instead. + */ export const LegacyTechDocsHome = () => { const tabsConfig = [ { diff --git a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx index 54c622fdf3..24555e01ae 100644 --- a/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx +++ b/plugins/techdocs/src/home/components/TechDocsCustomHome.tsx @@ -30,8 +30,8 @@ import { parseEntityRef, UserEntity, } from '@backstage/catalog-model'; -import { DocsTable } from './DocsTable'; -import { DocsCardGrid } from './DocsCardGrid'; +import { DocsTable } from './Tables'; +import { DocsCardGrid } from './Grids'; import { TechDocsPageWrapper } from './TechDocsPageWrapper'; import { @@ -51,8 +51,18 @@ const panels = { DocsCardGrid: DocsCardGrid, }; +/** + * Available panel types + * + * @public + */ export type PanelType = 'DocsCardGrid' | 'DocsTable'; +/** + * Type representing a TechDocsCustomHome panel. + * + * @public + */ export interface PanelConfig { title: string; description: string; @@ -61,11 +71,21 @@ export interface PanelConfig { filterPredicate: ((entity: Entity) => boolean) | string; } +/** + * Type representing a TechDocsCustomHome tab. + * + * @public + */ export interface TabConfig { label: string; panels: PanelConfig[]; } +/** + * Type representing a list of TechDocsCustomHome tabs. + * + * @public + */ export type TabsConfig = TabConfig[]; const CustomPanel = ({ diff --git a/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx b/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx index 453cfc22cc..52511bda19 100644 --- a/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx +++ b/plugins/techdocs/src/home/components/TechDocsPageWrapper.tsx @@ -19,11 +19,22 @@ import React from 'react'; import { PageWithHeader } from '@backstage/core-components'; import { useApi, configApiRef } from '@backstage/core-plugin-api'; -type Props = { +/** + * Props for {@link TechDocsPageWrapper} + * + * @public + */ +export type TechDocsPageWrapperProps = { children?: React.ReactNode; }; -export const TechDocsPageWrapper = ({ children }: Props) => { +/** + * Component wrapping a techdocs page with Page and Header components + * + * @public + */ +export const TechDocsPageWrapper = (props: TechDocsPageWrapperProps) => { + const { children } = props; const configApi = useApi(configApiRef); const generatedSubtitle = `Documentation available in ${ configApi.getOptionalString('organization.name') ?? 'Backstage' diff --git a/plugins/techdocs/src/home/components/TechDocsPicker.tsx b/plugins/techdocs/src/home/components/TechDocsPicker.tsx index ce79b9a4e9..32c7b800eb 100644 --- a/plugins/techdocs/src/home/components/TechDocsPicker.tsx +++ b/plugins/techdocs/src/home/components/TechDocsPicker.tsx @@ -34,6 +34,11 @@ type CustomFilters = DefaultEntityFilters & { techdocs?: TechDocsFilter; }; +/** + * Component responsible for updating TechDocs filters + * + * @public + */ export const TechDocsPicker = () => { const { updateFilters } = useEntityList(); diff --git a/plugins/techdocs/src/plugin.ts b/plugins/techdocs/src/plugin.ts index a37ad61f80..50360c4902 100644 --- a/plugins/techdocs/src/plugin.ts +++ b/plugins/techdocs/src/plugin.ts @@ -32,6 +32,11 @@ import { identityApiRef, } from '@backstage/core-plugin-api'; +/** + * The Backstage plugin that renders technical documentation for your components + * + * @public + */ export const techdocsPlugin = createPlugin({ id: 'techdocs', apis: [ @@ -73,6 +78,11 @@ export const techdocsPlugin = createPlugin({ }, }); +/** + * Routable extension used to render docs + * + * @public + */ export const TechdocsPage = techdocsPlugin.provide( createRoutableExtension({ name: 'TechdocsPage', @@ -81,6 +91,11 @@ export const TechdocsPage = techdocsPlugin.provide( }), ); +/** + * Routable extension used to render docs on Entity page + * + * @public + */ export const EntityTechdocsContent = techdocsPlugin.provide( createRoutableExtension({ name: 'EntityTechdocsContent', @@ -89,28 +104,11 @@ export const EntityTechdocsContent = techdocsPlugin.provide( }), ); -// takes a list of entities and renders documentation cards -export const DocsCardGrid = techdocsPlugin.provide( - createComponentExtension({ - name: 'DocsCardGrid', - component: { - lazy: () => - import('./home/components/DocsCardGrid').then(m => m.DocsCardGrid), - }, - }), -); - -// takes a list of entities and renders table listing documentation -export const DocsTable = techdocsPlugin.provide( - createComponentExtension({ - name: 'DocsTable', - component: { - lazy: () => import('./home/components/DocsTable').then(m => m.DocsTable), - }, - }), -); - -// takes a custom tabs config object and renders a documentation landing page +/** + * Component which takes a custom tabs config object and renders a documentation landing page. + * + * @public + */ export const TechDocsCustomHome = techdocsPlugin.provide( createRoutableExtension({ name: 'TechDocsCustomHome', @@ -122,6 +120,27 @@ export const TechDocsCustomHome = techdocsPlugin.provide( }), ); +/** + * Component which renders a default documentation landing page. + * + * @public + */ +export const DefaultTechDocsHome = techdocsPlugin.provide( + createRoutableExtension({ + name: 'DefaultTechDocsHome', + component: () => + import('./home/components/DefaultTechDocsHome').then( + m => m.DefaultTechDocsHome, + ), + mountPoint: rootRouteRef, + }), +); + +/** + * Responsible for rendering the provided router element + * + * @public + */ export const TechDocsIndexPage = techdocsPlugin.provide( createRoutableExtension({ name: 'TechDocsIndexPage', @@ -132,12 +151,3 @@ export const TechDocsIndexPage = techdocsPlugin.provide( mountPoint: rootRouteRef, }), ); - -export const TechDocsReaderPage = techdocsPlugin.provide( - createRoutableExtension({ - name: 'TechDocsReaderPage', - component: () => - import('./reader/components/TechDocsPage').then(m => m.TechDocsPage), - mountPoint: rootDocsRouteRef, - }), -); diff --git a/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx b/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx index f3384e21b3..c305dd1698 100644 --- a/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx +++ b/plugins/techdocs/src/reader/components/LegacyTechDocsPage.tsx @@ -22,8 +22,11 @@ import { TechDocsNotFound } from './TechDocsNotFound'; import { useApi } from '@backstage/core-plugin-api'; import { Page, Content } from '@backstage/core-components'; import { Reader } from './Reader'; -import { TechDocsPageHeader } from './TechDocsPageHeader'; +import { TechDocsReaderPageHeader } from './TechDocsReaderPageHeader'; +/** + * @deprecated Use {@link TechDocsPage} instead. + */ export const LegacyTechDocsPage = () => { const [documentReady, setDocumentReady] = useState(false); const { namespace, kind, name } = useParams(); @@ -53,7 +56,7 @@ export const LegacyTechDocsPage = () => { return ( - void; @@ -823,7 +828,7 @@ const TheReader = ({ entityRef, onReady = () => {}, withSearch = true, -}: Props) => { +}: ReaderProps) => { const classes = useStyles(); const dom = useTechDocsReaderDom(entityRef); const shadowDomRef = useRef(null); @@ -860,16 +865,20 @@ const TheReader = ({ ); }; -export const Reader = ({ - entityRef, - onReady = () => {}, - withSearch = true, -}: Props) => ( - - - -); +/** + * Component responsible for rendering TechDocs documentation + * + * @public + */ +export const Reader = (props: ReaderProps) => { + const { entityRef, onReady = () => {}, withSearch = true } = props; + return ( + + + + ); +}; diff --git a/plugins/techdocs/src/types.ts b/plugins/techdocs/src/types.ts index fbe6f4b870..ee6b88756c 100644 --- a/plugins/techdocs/src/types.ts +++ b/plugins/techdocs/src/types.ts @@ -16,11 +16,21 @@ import { Entity } from '@backstage/catalog-model'; +/** + * Metadata for TechDocs page + * + * @public + */ export type TechDocsMetadata = { site_name: string; site_description: string; }; +/** + * Metadata for TechDocs Entity + * + * @public + */ export type TechDocsEntityMetadata = Entity & { locationMetadata?: { type: string; target: string }; };