feat(docs-utils,dgeni): pull examples out of content and store in doc (#3389)

Author: griest024

libs/docs-utils/src/doc/api.type.ts

@@ -1,8 +1,10 @@
+import { DaffDocExample } from './example.type';
 import { DaffDoc } from './type';
 
 /**
  * An API doc that includes the type of the symbol.
  */
 export interface DaffApiDoc extends DaffDoc {
   docType: string;
+  examples: Array<DaffDocExample>;
 }

libs/docs-utils/src/doc/example.type.ts

@@ -0,0 +1,15 @@
+/**
+ * A usage example.
+ */
+export interface DaffDocExample {
+  /**
+   * The short caption describing the example.
+   * This should be just plain text.
+   */
+  caption: string;
+  /**
+   * The body of the example.
+   * Can be HTML and should be rendered as such.
+   */
+  body: string;
+}

libs/docs-utils/src/doc/public_api.ts

@@ -1,3 +1,4 @@
 export * from './api.type';
+export * from './example.type';
 export * from './guide.type';
 export * from './type';

tools/dgeni/src/processors/markdown.ts

@@ -10,6 +10,7 @@ import { Marked } from 'marked';
 import { markedHighlight } from 'marked-highlight';
 
 import {
+  DaffDocExample,
   DaffDocKind,
   daffDocsGetLinkUrl,
 } from '@daffodil/docs-utils';
@@ -80,10 +81,16 @@ export class MarkdownCodeProcessor implements FilterableProcessor {
   $process(docs: Document[]) {
     const ret = docs.map((doc) => {
       if (this.docTypes.includes(doc.docType)) {
-        doc[this.contentKey] = this.marked.parse(doc.content);
+        doc[this.contentKey] = this.marked.parse(typeof doc.description === 'undefined' ? doc.content : doc.description);
         if (doc.kind === DaffDocKind.PACKAGE || doc.kind === DaffDocKind.COMPONENT) {
           doc.description = this.docDescription;
         }
+        if (doc.examples) {
+          doc.examples = (<Array<DaffDocExample>>doc.examples).map((example) => ({
+            ...example,
+            body: this.marked.parse(example.body),
+          }));
+        }
         this.docDescription = null;
       };
       return doc;

tools/dgeni/src/transforms/daffodil-api-package/index.ts

@@ -1,4 +1,7 @@
-import { Package } from 'dgeni';
+import {
+  Document,
+  Package,
+} from 'dgeni';
 import linksPackage from 'dgeni-packages/links';
 import typescriptPackage from 'dgeni-packages/typescript';
 
@@ -42,6 +45,11 @@ import {
   DESIGN_PATH,
 } from '../config';
 import { daffodilBasePackage } from '../daffodil-base-package';
+import {
+  EXAMPLES_PROCESSOR_PROVIDER,
+  ExamplesProcessor,
+} from './processors/examples';
+import { ConvertToJsonProcessor } from '../../processors/convertToJson';
 
 const API_PACKAGE_NAME = 'daffodil-api';
 
@@ -62,6 +70,7 @@ export const apiDocsBase = new Package('api-base', [
   .processor(...ADD_SUBPACKAGE_EXPORTS_PROCESSOR_PROVIDER)
   .processor(...MARKDOWN_CODE_PROCESSOR_PROVIDER)
   .processor(...COLLECT_LINKABLE_SYMBOLS_PROCESSOR_PROVIDER)
+  .processor(...EXAMPLES_PROCESSOR_PROVIDER)
   .factory('API_DOC_TYPES_TO_RENDER', (EXPORT_DOC_TYPES) => EXPORT_DOC_TYPES.concat(['component', 'directive', 'pipe']))
   .config((readFilesProcessor, readTypeScriptModules, tsParser) => {
 
@@ -76,8 +85,15 @@ export const apiDocsBase = new Package('api-base', [
     readTypeScriptModules.basePath = API_SOURCE_PATH;
     readTypeScriptModules.hidePrivateMembers = true;
   })
-  .config((markdown: MarkdownCodeProcessor, EXPORT_DOC_TYPES, addKind: AddKindProcessor, breadcrumb: BreadcrumbProcessor) => {
+  .config((
+    markdown: MarkdownCodeProcessor,
+    EXPORT_DOC_TYPES,
+    addKind: AddKindProcessor,
+    breadcrumb: BreadcrumbProcessor,
+    examples: ExamplesProcessor,
+  ) => {
     markdown.docTypes.push(...EXPORT_DOC_TYPES);
+    examples.docTypes.push(...EXPORT_DOC_TYPES);
     addKind.docTypes.push(...EXPORT_DOC_TYPES, 'package', 'module');
     breadcrumb.docTypes.push(...EXPORT_DOC_TYPES, 'package');
     markdown.contentKey = 'description';
@@ -96,10 +112,22 @@ export const apiDocsBase = new Package('api-base', [
     parseTagsProcessor.tagDefinitions = parseTagsProcessor.tagDefinitions.concat([
       { name: 'docs-private' },
       { name: 'inheritdoc' },
+      {
+        name: 'example',
+        multi: true,
+        transforms: (doc: Document, tag: any, value: any) => {
+          const match = value.match(/^(.*)$/gm);
+          tag.caption = match[0];
+          tag.body = value.replace(match[0], '').trim();
+
+          return value;
+        },
+      },
     ]);
   })
-  .config((convertToJson, API_DOC_TYPES_TO_RENDER) => {
+  .config((convertToJson: ConvertToJsonProcessor, API_DOC_TYPES_TO_RENDER) => {
     convertToJson.docTypes = convertToJson.docTypes.concat(API_DOC_TYPES_TO_RENDER);
+    convertToJson.extraFields.push('examples');
   })
   .config((templateFinder) => {
     // Where to find the templates for the API doc rendering

tools/dgeni/src/transforms/daffodil-api-package/processors/examples.ts

@@ -0,0 +1,36 @@
+import { Document } from 'dgeni';
+
+import { DaffDocExample } from '@daffodil/docs-utils';
+
+import { MARKDOWN_CODE_PROCESSOR_NAME } from '../../../processors/markdown';
+import { FilterableProcessor } from '../../../utils/filterable-processor.type';
+
+export const EXAMPLES_PROCESSOR_NAME = 'examples';
+
+/**
+ * Adds subpackage entry point docs to the containing package doc.
+ */
+export class ExamplesProcessor implements FilterableProcessor {
+  readonly name = EXAMPLES_PROCESSOR_NAME;
+  readonly $runAfter = ['docs-processed'];
+  readonly $runBefore = ['rendering-docs', MARKDOWN_CODE_PROCESSOR_NAME];
+
+  docTypes = [];
+
+  $process(docs: Array<Document>): Array<Document> {
+    return docs.map((doc) => {
+      if (this.docTypes.includes(doc.docType)) {
+        doc.examples = doc.tags.tagsByName.get('example')?.map((example): DaffDocExample => ({
+          caption: example.caption,
+          body: example.body,
+        })) || [];
+      }
+      return doc;
+    });
+  }
+}
+
+export const EXAMPLES_PROCESSOR_PROVIDER = <const>[
+  EXAMPLES_PROCESSOR_NAME,
+  () => new ExamplesProcessor(),
+];