From 160b7a265c9fa8785021a3c6d631f2e4ecb10717 Mon Sep 17 00:00:00 2001 From: AmbrishRamachandiran Date: Wed, 22 Jan 2025 11:11:29 +0530 Subject: [PATCH] Updated docs of Software catalog docs Signed-off-by: AmbrishRamachandiran --- docs/features/software-catalog/api.md | 6 +++++- docs/features/software-catalog/descriptor-format.md | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md index ec699d2760..2a431d337b 100644 --- a/docs/features/software-catalog/api.md +++ b/docs/features/software-catalog/api.md @@ -214,7 +214,11 @@ if `prevCursor` exists, it can be used to retrieve the previous batch of entitie Lists entities. -**NOTE**: This endpoint is deprecated in favor of `GET /entities/by-query`, which provides a more efficient implementation and cursor based pagination. +:::note Note + +This endpoint is deprecated in favor of `GET /entities/by-query`, which provides a more efficient implementation and cursor based pagination. + +::: The endpoint supports the following query parameters, described in sections below: diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 17bdac56e9..28ddfae282 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -375,7 +375,9 @@ Fields of a link are: | `icon` | String | [Optional] A key representing a visual icon to be displayed in the UI. | | `type` | String | [Optional] An optional value to categorize links into specific groups. | -_NOTE_: The `icon` field value is meant to be a semantic key that will map to a +:::note Note + +The `icon` field value is meant to be a semantic key that will map to a specific icon that may be provided by an icon library (e.g. `material-ui` icons). These keys should be a sequence of `[a-z0-9A-Z]`, possibly separated by one of `[-_.]`. Backstage may support some basic icons out of the box such as those [defined in app-defaults](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx), but the @@ -383,6 +385,8 @@ Backstage integrator will ultimately be left to provide the appropriate icon component mappings. A generic fallback icon would be provided if a mapping cannot be resolved. +::: + The semantics of the `type` field are undefined. The adopter is free to define their own set of types and utilize them as they wish. Some potential use cases can be to utilize the type field to validate certain links exist on entities or to create customized UI components for specific link types. ## Common to All Kinds: Relations