feat(dgeni): consolidate docs nav list generation (#2989)

Author: griest024

tools/dgeni/src/processors/generateApiList.ts

@@ -0,0 +1,32 @@
+import {
+  Processor,
+  Document,
+} from 'dgeni';
+
+export class GenerateNavListProcessor implements Processor {
+  name = 'generateNavList';
+  $runAfter = ['docs-processed'];
+  $runBefore = ['rendering-docs'];
+  $validate = {
+    transform: {
+      presence: true,
+    },
+    outputFolder: {
+      presence: true,
+    },
+  };
+  outputFolder: string;
+  transform: (docs: Array<Document>) => Document;
+
+  $process(docs: Array<Document>): Array<Document> {
+    docs.push({
+      docType: 'navigation-list',
+      template: 'navigation-list.template.json',
+      path: this.outputFolder + '/index.json',
+      outputPath: this.outputFolder + '/index.json',
+      data: this.transform(docs),
+    });
+
+    return docs;
+  }
+}

tools/dgeni/src/processors/generateNavList.ts

@@ -0,0 +1,64 @@
+import { Document } from 'dgeni';
+
+import { GenerateNavListProcessor } from '../../../processors/generateNavList';
+
+interface DaffDocsApiNavigationList {
+  id: string;
+  title: string;
+  path: string;
+  docType: string;
+  docTypeShorthand: string;
+  children: Array<DaffDocsApiNavigationList>;
+}
+
+export const transformApiNavList: GenerateNavListProcessor['transform'] = (docs: Array<Document>): DaffDocsApiNavigationList => ({
+  id: '',
+  title: '',
+  path: '',
+  docType: '',
+  docTypeShorthand: '',
+  children: docs
+    .filter(doc => doc.docType === 'package')
+  // sort alphabetically
+    .sort((a, b) => {
+      if (a.name < b.name) {
+        return -1;
+      }
+      if (a.name > b.name) {
+        return 1;
+      }
+      return 0;
+    })
+    .map(doc => getPackageInfo(doc)),
+});
+
+function getPackageInfo(packageDoc): DaffDocsApiNavigationList {
+  return {
+    ...getExportInfo(packageDoc),
+    title: packageDoc.name,
+    docType: 'package',
+    docTypeShorthand: 'pk',
+    children: packageDoc.exports
+      .filter(doc => doc.docType !== 'package')
+      .map(getExportInfo),
+  };
+}
+
+function getExportInfo(exportDoc): DaffDocsApiNavigationList {
+  return {
+    id: exportDoc.id,
+    title: exportDoc.name,
+    path: `/${exportDoc.path}`,
+    docType: getDocType(exportDoc),
+    docTypeShorthand: exportDoc.docType.charAt(0),
+    children: [],
+  };
+}
+
+function getDocType(doc): DaffDocsApiNavigationList['docType'] {
+  // We map `let` and `var` types to `const`
+  if (['let', 'var'].indexOf(doc.docType) !== -1) {
+    return 'const';
+  }
+  return doc.docType;
+}

tools/dgeni/src/templates/api/api-list.template.json tools/dgeni/src/templates/api/navigation-list.template.json

@@ -1,13 +1,12 @@
 import { Package } from 'dgeni';
 
 import {
-  DAFF_DOC_KIND_PATH_SEGMENT_MAP,
   DAFF_DOCS_DESIGN_PATH,
   DAFF_DOCS_PATH,
   DaffDocKind,
 } from '@daffodil/docs-utils';
 
-import { outputPathsConfigurator } from './configurator/output';
+import { transformApiNavList } from './helpers/generateApiList';
 import { RemoveDuplicatesProcessor } from './processors/remove-duplicates';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
 import { AddInheritedDocsContentProcessor } from '../../processors/addInheritedDocsContent';
@@ -20,10 +19,11 @@ import {
 import { CrossEnvSafeNameProcessor } from '../../processors/cross-env-safe-name';
 import { FilterContainedDocsProcessor } from '../../processors/filterDocs';
 import { FilterOutPrivatePropertiesProcessor } from '../../processors/filterOutPrivateProperties';
-import { GenerateApiListProcessor } from '../../processors/generateApiList';
+import { GenerateNavListProcessor } from '../../processors/generateNavList';
 import { MakeTypesHtmlCompatibleProcessor } from '../../processors/makeTypesHtmlCompatible';
 import { MarkdownCodeProcessor } from '../../processors/markdown';
 import { PackagesProcessor } from '../../processors/packages';
+import { outputPathsConfigurator } from '../../utils/configurator/output';
 import {
   API_SOURCE_PATH,
   API_TEMPLATES_PATH,
@@ -90,11 +90,15 @@ export const apiDocsBase = new Package('api-base', [
   .config((templateFinder) => {
     // Where to find the templates for the API doc rendering
     templateFinder.templateFolders.unshift(API_TEMPLATES_PATH);
+  })
+  .config((generateNavList: GenerateNavListProcessor) => {
+    generateNavList.transform = transformApiNavList;
   });
 
 export const apiDocs = outputPathsConfigurator({
   kind: DaffDocKind.API,
   outputPath: DAFF_DOCS_PATH,
+  docTypes: ['package'],
 })(new Package(API_PACKAGE_NAME, [apiDocsBase]))
   .config((readTypeScriptModules) => {
     // Specify collections of source files that should contain the documentation to extract
@@ -106,6 +110,7 @@ export const apiDocs = outputPathsConfigurator({
 export const designApiPackage = outputPathsConfigurator({
   kind: DaffDocKind.API,
   outputPath: `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`,
+  docTypes: ['package'],
 })(new Package('design-api-docs', [apiDocs]))
   .processor(new RemoveDuplicatesProcessor())
   .config((readTypeScriptModules) => {

tools/dgeni/src/templates/guides/guide-list.template.json tools/dgeni/src/templates/guides/navigation-list.template.json

@@ -9,7 +9,7 @@ import {
 export class RemoveDuplicatesProcessor implements Processor {
   name = 'removeDuplicates';
   $runAfter = ['readTypeScriptModules'];
-  $runBefore = ['generateApiList', 'parsing-tags'];
+  $runBefore = ['generateNavList', 'parsing-tags'];
 
   $process(docs: Array<Document>): Array<Document> {
     const set = new Set();

tools/dgeni/src/transforms/daffodil-api-package/helpers/generateApiList.ts

@@ -0,0 +1,16 @@
+import { Document } from 'dgeni';
+
+export const transformGuideDoc = (doc: Document): TransformedDocument => ({
+  id: doc.id,
+  title: doc.title,
+  path: doc.path,
+  tableOfContents: doc.tableOfContents,
+});
+
+export interface TransformedDocument {
+  id: string;
+  title: string;
+  path: string;
+  tableOfContents: string;
+}
+

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

@@ -6,11 +6,14 @@ import {
   DaffDocKind,
 } from '@daffodil/docs-utils';
 
-import { outputPathsConfigurator } from './helpers/configurator/output';
-import { pathsConfigurator } from './helpers/configurator/path';
+import { transformGuideDoc } from './helpers/generateGuideList';
 import { guideFileReaderFactory } from './reader/guide-file.reader';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
+import { GenerateNavListProcessor } from '../../processors/generateNavList';
 import { MarkdownCodeProcessor } from '../../processors/markdown';
+import { outputPathsConfigurator } from '../../utils/configurator/output';
+import { pathsConfigurator } from '../../utils/configurator/path';
+import { generateNavigationTrieFromDocuments } from '../../utils/navigation-trie';
 import {
   API_SOURCE_PATH,
   DESIGN_PATH,
@@ -47,12 +50,16 @@ const base = new Package('daffodil-guides-base', [daffodilBasePackage])
         .replace(/\.\w*$/, ''),
       getAliases: (doc) => [doc.id],
     });
+  })
+  .config((generateNavList: GenerateNavListProcessor) => {
+    generateNavList.transform = (docs) => generateNavigationTrieFromDocuments(docs.map(transformGuideDoc));
   });
 
 // global
 export const packageDocsPackage = outputPathsConfigurator({
   kind: DaffDocKind.PACKAGE,
   outputPath: DAFF_DOCS_PATH,
+  docTypes: ['guide'],
 })(new Package('daffodil-package-docs', [base]))
   .config((readFilesProcessor) => {
     readFilesProcessor.basePath = API_SOURCE_PATH;
@@ -65,19 +72,22 @@ export const guideDocsPackage = pathsConfigurator({
   kind: DaffDocKind.GUIDE,
   outputPath: DAFF_DOCS_PATH,
   inputPathBase: DOCS_SOURCE_PATH,
+  docTypes: ['guide'],
 })(new Package('daffodil-guide', [base]));
 
 export const explanationDocsPackage = pathsConfigurator({
   kind: DaffDocKind.EXPLANATION,
   outputPath: DAFF_DOCS_PATH,
   inputPathBase: DOCS_SOURCE_PATH,
+  docTypes: ['guide'],
 })(new Package('daffodil-explanation', [base]));
 //
 
 // design
 export const designDocsPackage = outputPathsConfigurator({
   kind: DaffDocKind.PACKAGE,
   outputPath: `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`,
+  docTypes: ['guide'],
 })(new Package('design-packages', [base]))
   .config((readFilesProcessor) => {
     readFilesProcessor.basePath = DESIGN_PATH;
@@ -90,11 +100,13 @@ export const designGuidesPackage = pathsConfigurator({
   kind: DaffDocKind.GUIDE,
   outputPath: `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`,
   inputPathBase: DESIGN_PATH,
+  docTypes: ['guide'],
 })(new Package('design-guides', [base]));
 
 export const designExplanationsPackage = pathsConfigurator({
   kind: DaffDocKind.EXPLANATION,
   outputPath: `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`,
   inputPathBase: DESIGN_PATH,
+  docTypes: ['guide'],
 })(new Package('design-explanations', [base]));
 //

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

@@ -1,5 +1,5 @@
 import { Package } from 'dgeni';
-import { Configurator } from 'tools/dgeni/src/utils/configurator.type';
+import { Configurator } from 'tools/dgeni/src/utils/configurator/type';
 
 import {
   DaffDocKind,