From a68de3c984d5d2a000550f0f68a1454a5e3b9cd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anders=20N=C3=A4sman?= Date: Mon, 25 Apr 2022 15:51:17 +0200 Subject: [PATCH] move TechDocsStorage api from @backstage/plugin-techdocs to @backstage/plugin-techdocs-react MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Anders Näsman --- .../techdocs-cli-embedded-app/src/apis.ts | 2 +- plugins/techdocs-react/api-report.md | 29 +++++++++++++++ plugins/techdocs-react/src/api.ts | 37 +++++++++++++++++++ plugins/techdocs-react/src/index.ts | 4 +- plugins/techdocs/api-report.md | 6 +-- plugins/techdocs/src/plugin.ts | 5 ++- .../TechDocsReaderPageContent/dom.tsx | 2 +- .../src/reader/components/useReaderState.ts | 2 +- 8 files changed, 78 insertions(+), 9 deletions(-) diff --git a/packages/techdocs-cli-embedded-app/src/apis.ts b/packages/techdocs-cli-embedded-app/src/apis.ts index d230a9f83c..7156da902f 100644 --- a/packages/techdocs-cli-embedded-app/src/apis.ts +++ b/packages/techdocs-cli-embedded-app/src/apis.ts @@ -35,7 +35,7 @@ import { techdocsApiRef, TechDocsStorageApi, techdocsStorageApiRef, -} from '@backstage/plugin-techdocs'; +} from '@backstage/plugin-techdocs-react'; // TODO: Export type from plugin-techdocs and import this here // import { ParsedEntityId } from '@backstage/plugin-techdocs' diff --git a/plugins/techdocs-react/api-report.md b/plugins/techdocs-react/api-report.md index 264d59146e..fa38feef14 100644 --- a/plugins/techdocs-react/api-report.md +++ b/plugins/techdocs-react/api-report.md @@ -22,6 +22,9 @@ export function createTechDocsAddonExtension( // @alpha (undocumented) export const defaultTechDocsReaderPageValue: TechDocsReaderPageValue; +// @public +export type SyncResult = 'cached' | 'updated'; + // @alpha export const TECHDOCS_ADDONS_WRAPPER_KEY = 'techdocs.addons.wrapper.v1'; @@ -103,6 +106,32 @@ export type TechDocsReaderPageValue = { onReady?: () => void; }; +// @public +export interface TechDocsStorageApi { + // (undocumented) + getApiOrigin(): Promise; + // (undocumented) + getBaseUrl( + oldBaseUrl: string, + entityId: CompoundEntityRef, + path: string, + ): Promise; + // (undocumented) + getBuilder(): Promise; + // (undocumented) + getEntityDocs(entityId: CompoundEntityRef, path: string): Promise; + // (undocumented) + getStorageUrl(): Promise; + // (undocumented) + syncEntityDocs( + entityId: CompoundEntityRef, + logHandler?: (line: string) => void, + ): Promise; +} + +// @public +export const techdocsStorageApiRef: ApiRef; + // @alpha export const useShadowRoot: () => ShadowRoot | undefined; diff --git a/plugins/techdocs-react/src/api.ts b/plugins/techdocs-react/src/api.ts index 0d3c0b931a..6d726fae01 100644 --- a/plugins/techdocs-react/src/api.ts +++ b/plugins/techdocs-react/src/api.ts @@ -39,3 +39,40 @@ export interface TechDocsApi { export const techdocsApiRef = createApiRef({ id: 'plugin.techdocs.service', }); + +/** + * The outcome of a docs sync operation. + * + * @public + */ +export type SyncResult = 'cached' | 'updated'; + +/** + * API which talks to TechDocs storage to fetch files to render. + * + * @public + */ +export interface TechDocsStorageApi { + getApiOrigin(): Promise; + getStorageUrl(): Promise; + getBuilder(): Promise; + getEntityDocs(entityId: CompoundEntityRef, path: string): Promise; + syncEntityDocs( + entityId: CompoundEntityRef, + logHandler?: (line: string) => void, + ): Promise; + getBaseUrl( + oldBaseUrl: string, + entityId: CompoundEntityRef, + path: string, + ): Promise; +} + +/** + * Utility API reference for the {@link TechDocsStorageApi}. + * + * @public + */ +export const techdocsStorageApiRef = createApiRef({ + id: 'plugin.techdocs.storageservice', +}); diff --git a/plugins/techdocs-react/src/index.ts b/plugins/techdocs-react/src/index.ts index 8b46c9d717..c1cc3a1791 100644 --- a/plugins/techdocs-react/src/index.ts +++ b/plugins/techdocs-react/src/index.ts @@ -26,8 +26,8 @@ export { TechDocsAddons, TECHDOCS_ADDONS_WRAPPER_KEY, } from './addons'; -export { techdocsApiRef } from './api'; -export type { TechDocsApi } from './api'; +export { techdocsApiRef, techdocsStorageApiRef } from './api'; +export type { SyncResult, TechDocsApi, TechDocsStorageApi } from './api'; export { defaultTechDocsReaderPageValue, TechDocsReaderPageProvider, diff --git a/plugins/techdocs/api-report.md b/plugins/techdocs/api-report.md index a7c287a4f7..131a3a062a 100644 --- a/plugins/techdocs/api-report.md +++ b/plugins/techdocs/api-report.md @@ -191,7 +191,7 @@ export type ReaderState = { // @public export const Router: () => JSX.Element; -// @public +// @public @deprecated export type SyncResult = 'cached' | 'updated'; // @public @@ -394,7 +394,7 @@ export type TechDocsSearchResultListItemProps = { title?: string; }; -// @public +// @public @deprecated export interface TechDocsStorageApi { // (undocumented) getApiOrigin(): Promise; @@ -417,7 +417,7 @@ export interface TechDocsStorageApi { ): Promise; } -// @public +// @public @deprecated export const techdocsStorageApiRef: ApiRef; // @public diff --git a/plugins/techdocs/src/plugin.ts b/plugins/techdocs/src/plugin.ts index 2e3967cb6d..4ad8b98e37 100644 --- a/plugins/techdocs/src/plugin.ts +++ b/plugins/techdocs/src/plugin.ts @@ -14,7 +14,10 @@ * limitations under the License. */ -import { techdocsApiRef, techdocsStorageApiRef } from './api'; +import { + techdocsApiRef, + techdocsStorageApiRef, +} from '@backstage/plugin-techdocs-react'; import { TechDocsClient, TechDocsStorageClient } from './client'; import { rootDocsRouteRef, diff --git a/plugins/techdocs/src/reader/components/TechDocsReaderPageContent/dom.tsx b/plugins/techdocs/src/reader/components/TechDocsReaderPageContent/dom.tsx index e8d15e5231..7a373ab302 100644 --- a/plugins/techdocs/src/reader/components/TechDocsReaderPageContent/dom.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsReaderPageContent/dom.tsx @@ -26,7 +26,7 @@ import { useApi, configApiRef } from '@backstage/core-plugin-api'; import { SidebarPinStateContext } from '@backstage/core-components'; import { scmIntegrationsApiRef } from '@backstage/integration-react'; -import { techdocsStorageApiRef } from '../../../api'; +import { techdocsStorageApiRef } from '@backstage/plugin-techdocs-react'; import { useTechDocsReader } from './context'; diff --git a/plugins/techdocs/src/reader/components/useReaderState.ts b/plugins/techdocs/src/reader/components/useReaderState.ts index 39f09af264..c9dc9b5dbf 100644 --- a/plugins/techdocs/src/reader/components/useReaderState.ts +++ b/plugins/techdocs/src/reader/components/useReaderState.ts @@ -18,7 +18,7 @@ import { useApi } from '@backstage/core-plugin-api'; import { useMemo, useReducer, useRef } from 'react'; import useAsync from 'react-use/lib/useAsync'; import useAsyncRetry from 'react-use/lib/useAsyncRetry'; -import { techdocsStorageApiRef } from '../../api'; +import { techdocsStorageApiRef } from '@backstage/plugin-techdocs-react'; /** * @public