Updated documentation

Added comments to exports. Updated READMEs for the adr-backend and adr plugins.

Signed-off-by: Robert Bunning <rbunning@webstaurantstore.com>

plugins/adr-backend/README.md

@@ -4,6 +4,8 @@ This ADR backend plugin is primarily responsible for the following:
 
 - Provides a `DefaultAdrCollatorFactory`, which can be used in the search backend to index ADR documents associated with entities to your Backstage Search.
 
+- Provides endpoints that use UrlReaders for getting a ADR documents (used in the [ADR frontend plugin](../adr/README.md)).
+
 ## Indexing ADR documents for search
 
 Before you are able to start indexing ADR documents to search, you need to go through the [search getting started guide](https://backstage.io/docs/features/search/getting-started).

plugins/adr-backend/src/service/router.ts

@@ -18,6 +18,7 @@ import { UrlReader } from '@backstage/backend-common';
 import express from 'express';
 import Router from 'express-promise-router';
 
+/** @public */
 export async function createRouter(reader: UrlReader): Promise<express.Router> {
   const router = Router();
   router.use(express.json());

plugins/adr/README.md

@@ -4,7 +4,7 @@ Welcome to the ADR plugin!
 
 This plugin allows you to browse ADRs associated with your entities as well as a way to discover ADRs across others entities via Backstage Search. Use this to learn from the past experience of other projects to guide your own architecture decisions.
 
-NOTE: This plugin currently only supports entities/ADRs registered via GitHub integration.
+NOTE: By default, this plugin only supports entities/ADRs registered via GitHub integration. To get ADRs from other sites, see the [Using ADR plugin with sites other than GitHub](#using-adr-plugin-with-sites-other-than-github) section.
 
 ## Setup
 
@@ -77,6 +77,29 @@ case 'adr':
   );
 ```
 
+## Using ADR plugin with sites other than GitHub
+
+By default, the ADR plugin will only be able to retrieve ADRs through GitHub. If you would like to use it with other sites (for instance, AzureDevops):
+
+1. Make sure the [ADR backend plugin](../adr-backend/README.md) is installed.
+2. [Configure an integration](https://backstage.io/docs/integrations/) for the site you would like to pull ADRs from.
+3. Set the adrFileFetcher property on EntityAdrContent to urlReadersAdrFileFetcher:
+
+```jsx
+// In packages/app/src/components/catalog/EntityPage.tsx
+import { EntityAdrContent, isAdrAvailable, urlReaderAdrFileFetcher } from '@backstage/plugin-adr';
+
+...
+
+const serviceEntityPage = (
+  <EntityLayout>
+    {/* other tabs... */}
+    <EntityLayout.Route if={isAdrAvailable} path="/adrs" title="ADRs">
+      <EntityAdrContent adrFileFetcher={urlReaderAdrFileFetcher} />
+    </EntityLayout.Route>
+  </EntityLayout>
+```
+
 ## Custom ADR formats
 
 By default, this plugin will parse ADRs according to the format specified by the [Markdown Architecture Decision Record (MADR)](https://adr.github.io/madr/) template. If your ADRs are written using a different format, you can apply the following customizations to correctly identify and parse your documents:

plugins/adr/src/hooks/adrFileFetcher.ts

@@ -40,14 +40,36 @@ const useAdrApi = (
   };
 };
 
+/**
+ * Represents something that is capable of fetching a listing of adr files at a provided url
+ * and fetching the contents of an adr file at a provided url.
+ *
+ * @public
+ */
 export interface AdrFileFetcher {
+  /**
+   * A hook to get a listing of adr files that exist at the provided url
+   *
+   * @param url The url to get files from
+   */
   useGetAdrFilesAtUrl: (url: string) => any;
+
+  /**
+   * A hook to get the contents of the adr file at the provided url
+   *
+   * @param url The url of the adr file
+   */
   useReadAdrFileAtUrl: (url: string) => any;
 }
 
 const getAdrFilesEndpoint = 'getAdrFilesAtUrl';
 const readAdrFileEndpoint = 'readAdrFileAtUrl';
 
+/**
+ * An AdrFileFetcher that uses UrlReaders to fetch adr files
+ *
+ * @public
+ */
 export const urlReaderAdrFileFetcher: AdrFileFetcher = {
   useGetAdrFilesAtUrl: function (url: string) {
     const discoveryApi = useApi(discoveryApiRef);
@@ -63,6 +85,11 @@ export const urlReaderAdrFileFetcher: AdrFileFetcher = {
   },
 };
 
+/**
+ * An AdrFileFetcher that uses the useOctokitRequest hook for fetching adr files
+ *
+ * @public
+ */
 export const octokitAdrFileFetcher: AdrFileFetcher = {
   useGetAdrFilesAtUrl: (url: string) => useOctokitRequest(url),
   useReadAdrFileAtUrl: (url: string) => useOctokitRequest(url),

plugins/adr/src/index.ts

@@ -22,3 +22,4 @@ export { isAdrAvailable } from '@backstage/plugin-adr-common';
 export * from './components/AdrReader';
 export { adrPlugin, EntityAdrContent } from './plugin';
 export * from './search';
+export * from './hooks/adrFileFetcher';