UNPKG

@backstage/plugin-techdocs

Version:

The Backstage plugin that renders technical documentation for your components

731 lines (702 loc) • 23.7 kB
import { TechDocsMetadata, TechDocsEntityMetadata, TechDocsApi as TechDocsApi$1, TechDocsStorageApi as TechDocsStorageApi$1, SyncResult as SyncResult$1 } from '@backstage/plugin-techdocs-react'; import { CompoundEntityRef, Entity } from '@backstage/catalog-model'; import * as _backstage_core_plugin_api from '@backstage/core-plugin-api'; import { DiscoveryApi, FetchApi, IdentityApi } from '@backstage/core-plugin-api'; import { Config } from '@backstage/config'; import * as react_jsx_runtime from 'react/jsx-runtime'; import * as react from 'react'; import { ReactNode, PropsWithChildren, FC } from 'react'; import { ThemeOptions } from '@material-ui/core/styles'; import { ToolbarProps } from '@material-ui/core/Toolbar'; import { TableColumn, TableProps, TableOptions } from '@backstage/core-components'; import { UserListFilterKind, EntityOwnerPickerProps, EntityListPagination } from '@backstage/plugin-catalog-react'; import { CSSProperties } from '@material-ui/styles/withStyles'; import { EntityFilterQuery } from '@backstage/catalog-client'; import { SearchResultListItemExtensionProps } from '@backstage/plugin-search-react'; import { ResultHighlight } from '@backstage/plugin-search-common'; import { Overrides } from '@material-ui/core/styles/overrides'; import { StyleRules } from '@material-ui/core/styles/withStyles'; /** * Helper function that gives the children of {@link TechDocsReaderPage} access to techdocs and entity metadata * * @public */ type TechDocsReaderPageRenderFunction = (options: { techdocsMetadataValue?: TechDocsMetadata | undefined; entityMetadataValue?: TechDocsEntityMetadata | undefined; entityRef: CompoundEntityRef; /** * @deprecated You can continue pass this property, but directly to the `TechDocsReaderPageContent` component. */ onReady?: () => void; }) => JSX.Element; /** * Utility API reference for the {@link TechDocsStorageApi}. * * @public * @deprecated Import from `@backstage/plugin-techdocs-react` instead */ declare const techdocsStorageApiRef: _backstage_core_plugin_api.ApiRef<TechDocsStorageApi>; /** * Utility API reference for the {@link TechDocsApi}. * * @public * @deprecated Import from `@backstage/plugin-techdocs-react` instead */ declare const techdocsApiRef: _backstage_core_plugin_api.ApiRef<TechDocsApi>; /** * The outcome of a docs sync operation. * * @public * @deprecated Import from `@backstage/plugin-techdocs-react` instead */ type SyncResult = 'cached' | 'updated'; /** * API which talks to TechDocs storage to fetch files to render. * * @public * @deprecated Import from `@backstage/plugin-techdocs-react` instead */ interface TechDocsStorageApi { getApiOrigin(): Promise<string>; getStorageUrl(): Promise<string>; getBuilder(): Promise<string>; getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>; syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult>; getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>; } /** * API to talk to techdocs-backend. * * @public * @deprecated Import from `@backstage/plugin-techdocs-react` instead */ interface TechDocsApi { getApiOrigin(): Promise<string>; getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>; getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>; } /** * API to talk to `techdocs-backend`. * * @public */ declare class TechDocsClient implements TechDocsApi$1 { configApi: Config; discoveryApi: DiscoveryApi; private fetchApi; constructor(options: { configApi: Config; discoveryApi: DiscoveryApi; fetchApi: FetchApi; }); getCookie(): Promise<{ expiresAt: string; }>; getApiOrigin(): Promise<string>; /** * Retrieve TechDocs metadata. * * When docs are built, we generate a techdocs_metadata.json and store it along with the generated * static files. It includes necessary data about the docs site. This method requests techdocs-backend * which retrieves the TechDocs metadata. * * @param entityId - Object containing entity data like name, namespace, etc. */ getTechDocsMetadata(entityId: CompoundEntityRef): Promise<TechDocsMetadata>; /** * Retrieve metadata about an entity. * * This method requests techdocs-backend which uses the catalog APIs to respond with filtered * information required here. * * @param entityId - Object containing entity data like name, namespace, etc. */ getEntityMetadata(entityId: CompoundEntityRef): Promise<TechDocsEntityMetadata>; } /** * API which talks to TechDocs storage to fetch files to render. * * @public */ declare class TechDocsStorageClient implements TechDocsStorageApi$1 { configApi: Config; discoveryApi: DiscoveryApi; private fetchApi; constructor(options: { configApi: Config; discoveryApi: DiscoveryApi; fetchApi: FetchApi; /** @deprecated identityApi is not needed any more */ identityApi?: IdentityApi; }); getApiOrigin(): Promise<string>; getStorageUrl(): Promise<string>; getBuilder(): Promise<string>; /** * Fetch HTML content as text for an individual docs page in an entity's docs site. * * @param entityId - Object containing entity data like name, namespace, etc. * @param path - The unique path to an individual docs page e.g. overview/what-is-new * @returns HTML content of the docs page as string * @throws Throws error when the page is not found. */ getEntityDocs(entityId: CompoundEntityRef, path: string): Promise<string>; /** * Check if docs are on the latest version and trigger rebuild if not * * @param entityId - Object containing entity data like name, namespace, etc. * @param logHandler - Callback to receive log messages from the build process * @returns Whether documents are currently synchronized to newest version * @throws Throws error on error from sync endpoint in TechDocs Backend */ syncEntityDocs(entityId: CompoundEntityRef, logHandler?: (line: string) => void): Promise<SyncResult$1>; getBaseUrl(oldBaseUrl: string, entityId: CompoundEntityRef, path: string): Promise<string>; } /** * @public * A state representation that is used to configure the UI of <Reader /> */ type ContentStateTypes = /** There is nothing to display but a loading indicator */ 'CHECKING' /** There is no content yet -> present a full screen loading page */ | 'INITIAL_BUILD' /** There is content, but the backend is about to update it */ | 'CONTENT_STALE_REFRESHING' /** There is content, but after a reload, the content will be different */ | 'CONTENT_STALE_READY' /** There is content, the backend tried to update it, but failed */ | 'CONTENT_STALE_ERROR' /** There is nothing to see but a "not found" page. Is also shown on page load errors */ | 'CONTENT_NOT_FOUND' /** There is only the latest and greatest content */ | 'CONTENT_FRESH'; /** * @public shared reader state */ type ReaderState = { state: ContentStateTypes; path: string; contentReload: () => void; content?: string; contentErrorMessage?: string; syncErrorMessage?: string; buildLog: string[]; }; /** * @public Render function for {@link TechDocsReaderProvider} */ type TechDocsReaderProviderRenderFunction = (value: ReaderState) => JSX.Element; /** * @public Props for {@link TechDocsReaderProvider} */ type TechDocsReaderProviderProps = { children: TechDocsReaderProviderRenderFunction | ReactNode; }; /** * Provides shared building process state to the reader page components. * * @public */ declare const TechDocsReaderProvider: (props: TechDocsReaderProviderProps) => react_jsx_runtime.JSX.Element; /** * Props for {@link TechDocsReaderLayout} * @public */ type TechDocsReaderLayoutProps = { /** * Show or hide the header, defaults to true. */ withHeader?: boolean; /** * Show or hide the content search bar, defaults to true. */ withSearch?: boolean; }; /** * Default TechDocs reader page structure composed with a header and content * @public */ declare const TechDocsReaderLayout: (props: TechDocsReaderLayoutProps) => react_jsx_runtime.JSX.Element; /** * @public */ type TechDocsReaderPageProps = { entityRef?: CompoundEntityRef; children?: TechDocsReaderPageRenderFunction | ReactNode; overrideThemeOptions?: Partial<ThemeOptions>; }; /** * Props for {@link TechDocsReaderPageHeader} * * @public * @deprecated No need to pass down properties anymore. The component consumes data from `TechDocsReaderPageContext` instead. Use the {@link @backstage/plugin-techdocs-react#useTechDocsReaderPage} hook for custom header. */ type TechDocsReaderPageHeaderProps = PropsWithChildren<{ entityRef?: CompoundEntityRef; entityMetadata?: TechDocsEntityMetadata; techDocsMetadata?: TechDocsMetadata; }>; /** * Renders the reader page header. * This component does not accept props, please use * the Tech Docs add-ons to customize it * @public */ declare const TechDocsReaderPageHeader: (props: TechDocsReaderPageHeaderProps) => react_jsx_runtime.JSX.Element | null; /** * Props for {@link TechDocsReaderPageContent} * @public */ type TechDocsReaderPageContentProps = { /** * @deprecated No need to pass down entityRef as property anymore. Consumes the entityName from `TechDocsReaderPageContext`. Use the {@link @backstage/plugin-techdocs-react#useTechDocsReaderPage} hook for custom reader page content. */ entityRef?: CompoundEntityRef; /** * Path in the docs to render by default. This should be used when rendering docs for an entity that specifies the * "backstage.io/techdocs-entity-path" annotation for deep linking into another entities docs. */ defaultPath?: string; /** * Show or hide the search bar, defaults to true. */ withSearch?: boolean; /** * If {@link TechDocsReaderPageContentProps.withSearch | withSearch} is true, * this will redirect the search result urls, e.g. turn search results into * links within the "Docs" tab of the entity page, instead of the global docs * page. */ searchResultUrlMapper?: (url: string) => string; /** * Callback called when the content is rendered. */ onReady?: () => void; }; /** * Renders the reader page content * @public */ declare const TechDocsReaderPageContent: (props: TechDocsReaderPageContentProps) => react_jsx_runtime.JSX.Element; /** * Component responsible for rendering TechDocs documentation * @public * @deprecated use `TechDocsReaderPageContent` component instead. */ declare const Reader: (props: TechDocsReaderPageContentProps) => react_jsx_runtime.JSX.Element; /** * Renders the reader page subheader. * Please use the Tech Docs add-ons to customize it * @public */ declare const TechDocsReaderPageSubheader: (props: { toolbarProps?: ToolbarProps; }) => react_jsx_runtime.JSX.Element | null; /** * Props for {@link TechDocsSearch} * * @public */ type TechDocsSearchProps = { entityId: CompoundEntityRef; entityTitle?: string; debounceTime?: number; searchResultUrlMapper?: (url: string) => string; }; /** * Component used to render search bar on TechDocs page, scoped to * * @public */ declare const TechDocsSearch: (props: TechDocsSearchProps) => react_jsx_runtime.JSX.Element; /** * Props for {@link EntityListDocsGrid} * * @public */ type DocsGroupConfig = { title: ReactNode; filterPredicate: ((entity: Entity) => boolean) | string; }; /** * Props for {@link EntityListDocsGrid} * * @public */ type EntityListDocsGridPageProps = { groups?: DocsGroupConfig[]; }; /** * Component responsible to get entities from entity list context and pass down to DocsCardGrid * * @public */ declare const EntityListDocsGrid: (props: EntityListDocsGridPageProps) => react_jsx_runtime.JSX.Element; /** * Props for {@link DocsCardGrid} * * @public */ type DocsCardGridProps = { entities: Entity[] | undefined; }; /** * Component which accepts a list of entities and renders a item card for each entity * * @public */ declare const DocsCardGrid: (props: DocsCardGridProps) => react_jsx_runtime.JSX.Element | null; /** @public */ type InfoCardGridClassKey = 'linkSpacer' | 'readMoreLink'; /** * Props for {@link InfoCardGrid} * * @public */ type InfoCardGridProps = { entities: Entity[] | undefined; linkContent?: string | JSX.Element; linkDestination?: (entity: Entity) => string | undefined; }; /** * Component which accepts a list of entities and renders a info card for each entity * * @public */ declare const InfoCardGrid: (props: InfoCardGridProps) => react_jsx_runtime.JSX.Element | null; /** * Generic representing the metadata structure for a docs table row. * * @public */ type DocsTableRow = { entity: Entity; resolved: { docsUrl: string; ownedByRelationsTitle: string; ownedByRelations: CompoundEntityRef[]; }; }; /** * Props for {@link EntityListDocsTable}. * * @public */ type EntityListDocsTableProps = { columns?: TableColumn<DocsTableRow>[]; actions?: TableProps<DocsTableRow>['actions']; options?: TableOptions<DocsTableRow>; }; /** * Component which renders a table with entities from catalog. * * @public */ declare const EntityListDocsTable: { (props: EntityListDocsTableProps): react_jsx_runtime.JSX.Element; columns: { createTitleColumn(options?: { hidden?: boolean; }): TableColumn<DocsTableRow>; createNameColumn(): TableColumn<DocsTableRow>; createOwnerColumn(): TableColumn<DocsTableRow>; createKindColumn(): TableColumn<DocsTableRow>; createTypeColumn(): TableColumn<DocsTableRow>; }; actions: { createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => { icon: () => react_jsx_runtime.JSX.Element; tooltip: string; onClick: () => any; }; createStarEntityAction(isStarredEntity: Function, toggleStarredEntity: Function): (row: DocsTableRow) => { cellStyle: { paddingLeft: string; }; icon: () => react_jsx_runtime.JSX.Element; tooltip: string; onClick: () => any; }; }; }; /** * Props for {@link DocsTable}. * * @public */ type DocsTableProps = { entities: Entity[] | undefined; title?: string | undefined; loading?: boolean | undefined; columns?: TableColumn<DocsTableRow>[]; actions?: TableProps<DocsTableRow>['actions']; options?: TableOptions<DocsTableRow>; }; /** * Component which renders a table documents * * @public */ declare const DocsTable: { (props: DocsTableProps): react_jsx_runtime.JSX.Element | null; columns: { createTitleColumn(options?: { hidden?: boolean; }): TableColumn<DocsTableRow>; createNameColumn(): TableColumn<DocsTableRow>; createOwnerColumn(): TableColumn<DocsTableRow>; createKindColumn(): TableColumn<DocsTableRow>; createTypeColumn(): TableColumn<DocsTableRow>; }; actions: { createCopyDocsUrlAction(copyToClipboard: Function): (row: DocsTableRow) => { icon: () => react_jsx_runtime.JSX.Element; tooltip: string; onClick: () => any; }; createStarEntityAction(isStarredEntity: Function, toggleStarredEntity: Function): (row: DocsTableRow) => { cellStyle: { paddingLeft: string; }; icon: () => react_jsx_runtime.JSX.Element; tooltip: string; onClick: () => any; }; }; }; /** * Props for {@link TechDocsIndexPage} * * @public */ type TechDocsIndexPageProps = { initialFilter?: UserListFilterKind; columns?: TableColumn<DocsTableRow>[]; actions?: TableProps<DocsTableRow>['actions']; ownerPickerMode?: EntityOwnerPickerProps['mode']; pagination?: EntityListPagination; options?: TableOptions<DocsTableRow>; PageWrapper?: FC; CustomHeader?: FC; }; /** * Props for {@link DefaultTechDocsHome} * * @public * @deprecated Please use `TechDocsIndexPageProps` instead. */ type DefaultTechDocsHomeProps = TechDocsIndexPageProps; /** * Component which renders a default documentation landing page. * * @public */ declare const DefaultTechDocsHome: (props: TechDocsIndexPageProps) => react_jsx_runtime.JSX.Element; /** * Available panel types * * @public */ type PanelType = 'DocsCardGrid' | 'DocsTable' | 'TechDocsIndexPage' | 'InfoCardGrid'; /** * Type representing Panel props * * @public */ interface PanelProps { options?: TableOptions<DocsTableRow>; linkContent?: string | JSX.Element; linkDestination?: (entity: Entity) => string | undefined; PageWrapper?: FC; CustomHeader?: FC; } /** * Type representing a TechDocsCustomHome panel. * * @public */ interface PanelConfig { title: string; description: string; panelType: PanelType; panelCSS?: CSSProperties; filterPredicate: ((entity: Entity) => boolean) | string; panelProps?: PanelProps; } /** * Type representing a TechDocsCustomHome tab. * * @public */ interface TabConfig { label: string; panels: PanelConfig[]; } /** * Type representing a list of TechDocsCustomHome tabs. * * @public */ type TabsConfig = TabConfig[]; /** * Component which can be used to render entities in a custom way. * * @public */ declare const CustomDocsPanel: ({ config, entities, index, }: { config: PanelConfig; entities: Entity[]; index: number; }) => react_jsx_runtime.JSX.Element; /** * Props for {@link TechDocsCustomHome} * * @public */ type TechDocsCustomHomeProps = { tabsConfig: TabsConfig; filter?: EntityFilterQuery; CustomPageWrapper?: FC; }; /** * Props for {@link TechDocsPageWrapper} * * @public */ type TechDocsPageWrapperProps = { children?: ReactNode; CustomPageWrapper?: FC<{ children?: ReactNode; }>; }; /** * Component wrapping a TechDocs page with Page and Header components * * @public */ declare const TechDocsPageWrapper: (props: TechDocsPageWrapperProps) => react_jsx_runtime.JSX.Element; /** * Component responsible for updating TechDocs filters * * @public */ declare const TechDocsPicker: () => null; /** * Props for {@link TechDocsSearchResultListItem}. * * @public */ type TechDocsSearchResultListItemProps = { icon?: ReactNode | ((result: any) => ReactNode); result?: any; highlight?: ResultHighlight; rank?: number; lineClamp?: number; asListItem?: boolean; asLink?: boolean; title?: string; }; /** * The Backstage plugin that renders technical documentation for your components * * @public */ declare const techdocsPlugin: _backstage_core_plugin_api.BackstagePlugin<{ root: _backstage_core_plugin_api.RouteRef<undefined>; docRoot: _backstage_core_plugin_api.RouteRef<{ name: string; kind: string; namespace: string; }>; entityContent: _backstage_core_plugin_api.RouteRef<undefined>; }, {}>; /** * Routable extension used to render docs * * @public */ declare const TechdocsPage: () => react_jsx_runtime.JSX.Element; /** * Routable extension used to render docs on Entity page * * @public */ declare const EntityTechdocsContent: ({ children, withSearch, }: react.PropsWithChildren<{ withSearch?: boolean; }>) => react_jsx_runtime.JSX.Element; /** * Component which takes a custom tabs config object and renders a documentation landing page. * * @public */ declare const TechDocsCustomHome: (props: TechDocsCustomHomeProps) => react_jsx_runtime.JSX.Element; /** * Responsible for rendering the provided router element * * @public */ declare const TechDocsIndexPage: (props: TechDocsIndexPageProps) => react_jsx_runtime.JSX.Element; /** * Component responsible for composing a TechDocs reader page experience * * @public */ declare const TechDocsReaderPage: (props: TechDocsReaderPageProps) => react_jsx_runtime.JSX.Element; /** * React extension used to render results on Search page or modal * * @public */ declare const TechDocsSearchResultListItem: (props: SearchResultListItemExtensionProps<TechDocsSearchResultListItemProps>) => JSX.Element | null; /** * Helper that takes in entity and returns true/false if TechDocs is available for the entity * * @public */ declare const isTechDocsAvailable: (entity: Entity) => boolean; /** * Responsible for registering routes for TechDocs, TechDocs Homepage and separate TechDocs page * * @public */ declare const Router: () => react_jsx_runtime.JSX.Element; /** * Responsible for registering route to view docs on Entity page * * @public */ declare const LegacyEmbeddedDocsRouter: ({ children, withSearch, }: PropsWithChildren<{ withSearch?: boolean; }>) => react_jsx_runtime.JSX.Element; /** @public */ type CatalogReactComponentsNameToClassKey = { BackstageInfoCardGrid: InfoCardGridClassKey; }; /** @public */ type BackstageOverrides = Overrides & { [Name in keyof CatalogReactComponentsNameToClassKey]?: Partial<StyleRules<CatalogReactComponentsNameToClassKey[Name]>>; }; declare module '@backstage/theme' { interface OverrideComponentNameToClassKeys extends CatalogReactComponentsNameToClassKey { } } /** * The Backstage plugin that renders technical documentation for your components * * @packageDocumentation */ /** * @deprecated Import from `@backstage/plugin-techdocs-react` instead * * @public */ type DeprecatedTechDocsMetadata = TechDocsMetadata; /** * @deprecated Import from `@backstage/plugin-techdocs-react` instead * * @public */ type DeprecatedTechDocsEntityMetadata = TechDocsEntityMetadata; export { type BackstageOverrides, type CatalogReactComponentsNameToClassKey, type ContentStateTypes, CustomDocsPanel, DefaultTechDocsHome, type DefaultTechDocsHomeProps, DocsCardGrid, type DocsCardGridProps, type DocsGroupConfig, DocsTable, type DocsTableProps, type DocsTableRow, LegacyEmbeddedDocsRouter as EmbeddedDocsRouter, EntityListDocsGrid, type EntityListDocsGridPageProps, EntityListDocsTable, type EntityListDocsTableProps, EntityTechdocsContent, InfoCardGrid, type InfoCardGridClassKey, type InfoCardGridProps, type PanelConfig, type PanelProps, type PanelType, Reader, type ReaderState, Router, type SyncResult, type TabConfig, type TabsConfig, type TechDocsApi, TechDocsClient, TechDocsCustomHome, type TechDocsCustomHomeProps, type DeprecatedTechDocsEntityMetadata as TechDocsEntityMetadata, TechDocsIndexPage, type TechDocsIndexPageProps, type DeprecatedTechDocsMetadata as TechDocsMetadata, TechDocsPageWrapper, type TechDocsPageWrapperProps, TechDocsPicker, TechDocsReaderLayout, type TechDocsReaderLayoutProps, TechDocsReaderPage, TechDocsReaderPageContent, type TechDocsReaderPageContentProps, TechDocsReaderPageHeader, type TechDocsReaderPageHeaderProps, type TechDocsReaderPageProps, type TechDocsReaderPageRenderFunction, TechDocsReaderPageSubheader, TechDocsReaderProvider, type TechDocsReaderProviderProps, type TechDocsReaderProviderRenderFunction, TechDocsSearch, type TechDocsSearchProps, TechDocsSearchResultListItem, type TechDocsSearchResultListItemProps, type TechDocsStorageApi, TechDocsStorageClient, TechdocsPage, isTechDocsAvailable, techdocsPlugin as plugin, techdocsApiRef, techdocsPlugin, techdocsStorageApiRef };