Update Readme to include information on how to add a "getting-started" to the API catalog (#214)

* Move content under resources

* Adding how-to add a getting started section

* Fix img uri

* Update README.md

Author: josejulio

README.md

@@ -98,6 +98,33 @@ To be more bot-friendly we pre-render the whole site to allow it to be crawled.
 You can run trigger a local run by building the site `npm run build` and then running `npm run prerender`. The results of the pre-rendering are written in
 [build/pre-rendered](./build/pre-rendered)
 
+## Adding external content
+
+Details from each API is extracted from its openapi file to show in the API catalog. Sometimes this is not enough.
+We provide an option to add additional sections. Each section is specified as a [markdown file](https://www.markdownguide.org/basic-syntax/) 
+and has a specific place on the API catalog.
+
+The content is rendered in the API catalog using the same look and feel. Here is an example of a 
+[getting started](./examples/getting-started.md) section:
+
+![Getting started sample](./examples/getting-started.png?raw=true "Getting started sample")
+
+### Adding a section
+
+A markdown file needs to be added to [./packages/discovery/resources/content](./packages/discovery/resources/content)
+under the group-id and api-id using one of the [supported sections](#supported-sections) filenames.
+
+e.g. to add Getting started section for Notifications we need to create the following file:
+[./packages/discovery/resources/content/hcc-insights/notifications/getting-started.md](./packages/discovery/resources/content/hcc-insights/notifications/getting-started.md)
+
+This file will be used when regenerating the API files to add a new section on the API catalog.
+
+### Supported sections
+
+This is a list of the support sections, followed by the required file name.
+
+- Getting started: `getting-started.md`
+
 ## Releasing to Production
 
 We use GitLab tags for deployment to Production. Follow these steps:

examples/getting-started.md

@@ -0,0 +1,52 @@
+## Ostendit una oculos
+
+*Lorem markdownum solus*. Coniuge hospita ignarus, rostrisque respondit geminas
+Corintho pluma.
+
+    key = downPmuParity / e - -3 + monitor_dimm_bitmap + page * 1 +
+            card_dot_serial;
+    var byte_isp = 5;
+    var logic = crossplatform(iscsi.olapWebsiteAccess(tokenLeak, -2), 407696);
+    surface.disk(upnp_leaf_reimage);
+
+## Acti membra custodia tantaque iuveni Meleagron terrae
+
+*Virum* femineae in [imago in desideret](http://sesimul.io/nempe-acu.php) dona,
+sub arma quis annum arbore. Et aderant Editus, erubuit dolore lacertos prudens
+pedum: atrox inque! Mallem ait cuius, Prospicientis Ammon.
+
+## Anno fert miserrima mortis post cista
+
+Tenebat spes fontibus sceptra; Cythereia Nocte trepidumque mihi ramosque ego
+epulis, modo. Atque non sibi clam pudore, tenues somnus murmure [adlevat
+ululavit](http://sisacro.com/auditurumacuto).
+
+- Mira limite
+- Progenitore aut
+- Formasque stillabant terras
+
+## Simus insignia exuit saturos
+
+Matertera ardent; mox quo inminet brevi, passuque ante poscenti perfida coeunt
+vel et iuncta sanguine tergum. Volentem superi in quid alto quoque coniugium
+fata *dubitanti illa* hospes ubi quanto animos, esse. Avorum Serpens undae et
+taurum nubibus est exilio: [coniugis censu](http://obliquo.net/).
+
+## Aethon iactum si foret viro
+
+Luco mihi, fata ire auras, hic cuius ille, minus oraque? Considerat parva
+spectabilis haec!
+
+> Suis mecum [vehebat et et](http://www.cum-abest.org/) quoque, virique
+> parantem. Ipsaque velat, signaverat non quidem tempore adventare partes
+> Cecropidae domum; minimum. Pignus auxiliumque colla avari Iason piget plura
+> auctor sedes quod plura. *Materno* fuit vidit amat vidit rumpe est iam optatae
+> Eurytus [Asterien](http://tum.io/); praestantes decor, enim quo rogata
+> differtis vidit?
+
+Atque ab eligit arma caede, in ad aures, ait humo cibos Cecropios sucos ductae.
+Non sacra qua mente viriles classe tu signa venientis domus et o passus patulas
+cauda non; gravis. Exemit luctatur neque, *peragant* ignes quaesierat aglauros
+et nigrum amorem.
+
+Generated from: https://github.com/jaspervdj/lorem-markdownum/

examples/getting-started.png

@@ -0,0 +1,3 @@
+export const RESOURCES_DIR = ['resources'];
+export const CONTENT_DIR = [...RESOURCES_DIR, 'content'];
+export const OPENAPI_DIR = [...RESOURCES_DIR, 'api'];

packages/discovery/content/empty renamed to packages/discovery/resources/content/empty

@@ -3,24 +3,22 @@ import {existsSync, readdirSync, readFileSync} from "fs";
 import path from "path";
 import snakeCase from 'lodash.snakecase';
 import {ExtraAPIContent} from "@apidocs/common";
+import {CONTENT_DIR} from "./constants";
 
 export type DocumentationMap = {
     [documentationType: string]: string;
 }
 
 const acceptedExtensions: ReadonlyArray<string> = [ '.md' ];
 
-const CONTENT_DIR = 'content';
-
-
 const isDocumentation = (maybeDocumentation: string): boolean => {
     return (Object.values(ExtraAPIContent) as ReadonlyArray<string>).includes(maybeDocumentation);
 }
 
 export const getDocumentationContents = (group: Group, app: App, baseDir: string): DocumentationMap => {
     const pathToContent = path.resolve(
         baseDir,
-        CONTENT_DIR,
+        ...CONTENT_DIR,
         group.id,
         app.id
     );

packages/transform/src/constants.ts

@@ -13,6 +13,7 @@ import {OpenAPI, OpenAPIV3} from "openapi-types";
 import sortedJsonStringify from 'sorted-json-stringify';
 import {getDocumentationContents} from "./documentation";
 import {APIContent} from "@apidocs/common";
+import {OPENAPI_DIR} from "./constants";
 
 interface Options {
     inputDir: string;
@@ -59,8 +60,7 @@ const getOpenAPIContent = async (discoveryPath: string, app: App, group: string,
     if (app.useLocalFile) {
         return readFileSync(path.resolve(
             discoveryPath,
-            'resources',
-            'api',
+            ...OPENAPI_DIR,
             group,
             app.id,
             'openapi.json'