docs: create readme documentation

Signed-off-by: Alisson Fabiano <afabiano@eshopworld.com>
2022-08-12 16:53:57 +01:00
parent f253a8e65f
commit b3bafea79a
2 changed files with 51 additions and 0 deletions
@@ -22,6 +22,12 @@ Lists all Git Tags for a given repository

 ![Azure Repos Git Tags Example](./docs/azure-devops-git-tags.png)

+### Azure Readme
+
+Readme for a given repository
+
+![Azure Readme Example](./docs/azure-devops-readme.png)
+
 ## Setup

 The following sections will help you get the Azure DevOps plugin setup and running
@@ -197,6 +203,51 @@ To get the Git Tags component working you'll need to do the following two steps:
 - You'll need to add the `EntityLayout.Route` above from step 2 to all the entity sections you want to see Git Tags in. For example if you wanted to see Git Tags when looking at Website entities then you would need to add this to the `websiteEntityPage` section.
 - The `if` prop is optional on the `EntityLayout.Route`, you can remove it if you always want to see the tab even if the entity being viewed does not have the needed annotation

+### Git README
+
+To get the README component working you'll need to do the following two steps:
+
+1. First we need to add the @backstage/plugin-azure-devops package to your frontend app:
+
+   ```bash
+   # From your Backstage root directory
+   yarn add --cwd packages/app @backstage/plugin-azure-devops
+   ```
+
+2. Second we need to add the `EntityAzureReadmeCard` extension to the entity page in your app:
+
+   ```tsx
+   // In packages/app/src/components/catalog/EntityPage.tsx
+   import {
+     EntityAzureReadmeCard,
+     isAzureDevOpsAvailable,
+   } from '@backstage/plugin-azure-devops';
+
+   // As it is a card, you can customize it the way you prefer
+   // For example in the Service section
+
+   const overviewContent = (
+     <Grid container spacing={3} alignItems="stretch">
+       <EntitySwitch>
+         <EntitySwitch.Case if={isAzureDevOpsAvailable}>
+           <Grid item md={6}>
+             ...
+           </Grid>
+           <Grid item md={6}>
+             <EntityAzureReadmeCard maxHeight={350} />
+           </Grid>
+         </EntitySwitch.Case>
+       </EntitySwitch>
+     </Grid>
+   );
+   ```
+
+**Notes:**
+
+- You'll need to add the `EntitySwitch.Case` above from step 2 to all the entity sections you want to see Readme in. For example if you wanted to see Readme when looking at Website entities then you would need to add this to the `websiteEntityPage` section.
+- The `if` prop is optional on the `EntitySwitch.Case`, you can remove it if you always want to see the tab even if the entity being viewed does not have the needed annotation
+- The `maxHeight` property on the `EntityAzureReadmeCard` will set the maximum screen size you would like to see, if not set it will default to 100%
+
 ## Limitations

 - Currently multiple organizations are not supported