feat(dgeni): render subpackages under root package (#3063)

tools/dgeni/src/processors/packages.ts

@@ -6,13 +6,17 @@ import * as path from 'path';
 
 import { API_SOURCE_PATH } from '../transforms/config';
 
+export interface DocumentWithDepth extends Document {
+  depth?: number;
+}
+
 export class PackagesProcessor implements Processor {
   name = 'packages';
   $runBefore = ['computing-ids'];
   docTypes = [];
   nameComputer = (id: string): string => `@daffodil/${id}`;
 
-  $process(docs: Document[]): Document[] {
+  $process(docs: Document[]): DocumentWithDepth[] {
     return docs.map(doc => {
       if (doc.docType === 'module') {
         doc.id = doc.id
@@ -26,6 +30,8 @@ export class PackagesProcessor implements Processor {
         } catch {}
         // The name is actually the full id
         doc.name = this.nameComputer(doc.id);
+        // root packages should have depth of 0
+        doc.depth = doc.id.split('/').length - 1;
       }
       return doc;
     });

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

@@ -1,6 +1,5 @@
-import { Document } from 'dgeni';
-
 import { GenerateNavListProcessor } from '../../../processors/generateNavList';
+import { DocumentWithDepth } from '../../../processors/packages';
 
 interface DaffDocsApiNavigationList {
   id: string;
@@ -31,14 +30,14 @@ const comparePackage = (aDoc: {name: string}, bDoc: {name: string}): -1 | 0 | 1
   );
 };
 
-export const transformApiNavList: GenerateNavListProcessor['transform'] = (docs: Array<Document>): DaffDocsApiNavigationList => ({
+export const transformApiNavList: GenerateNavListProcessor['transform'] = (docs: Array<DocumentWithDepth>): DaffDocsApiNavigationList => ({
   id: '',
   title: '',
   path: '',
   docType: '',
   docTypeShorthand: '',
   children: docs
-    .filter(doc => doc.docType === 'package')
+    .filter(doc => doc.docType === 'package' && doc.depth === 0)
     // sort alphabetically
     .sort(comparePackage)
     .map(doc => getPackageInfo(doc)),
@@ -52,7 +51,6 @@ export function getPackageInfo(packageDoc): DaffDocsApiNavigationList {
     docType: 'package',
     docTypeShorthand: 'pk',
     children: packageDoc.exports
-      .filter(doc => doc.docType !== 'package')
       .map(getExportInfo),
   };
 }
@@ -64,7 +62,10 @@ function getExportInfo(exportDoc): DaffDocsApiNavigationList {
     path: `${exportDoc.path[0] === '/' ? '' : '/'}${exportDoc.path}`,
     docType: getDocType(exportDoc),
     docTypeShorthand: exportDoc.docType.charAt(0),
-    children: [],
+    children: exportDoc.docType === 'package'
+      ? exportDoc.exports
+        .map(getExportInfo)
+      : [],
   };
 }
 

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

@@ -8,6 +8,7 @@ import {
 
 import { transformApiNavList } from './helpers/generateApiList';
 import { AddPackageExportsProcessor } from './processors/add-package-exports';
+import { AddSubpackageExportsProcessor } from './processors/add-subpackage-exports';
 import { RemoveDuplicatesProcessor } from './processors/remove-duplicates';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
 import { AddKindProcessor } from '../../processors/add-kind';
@@ -44,7 +45,6 @@ export const apiDocsBase = new Package('api-base', [
   linksPackage,
 ])
   .processor(new CrossEnvSafeNameProcessor())
-  //Register Processors for this package
   .processor(new FilterContainedDocsProcessor())
   .processor(new CleanSelectorsProcessor())
   .processor(new MakeTypesHtmlCompatibleProcessor())
@@ -53,10 +53,10 @@ export const apiDocsBase = new Package('api-base', [
   .processor(new AddLinkTagToDaffodilReferencesProcessor())
   .processor(new PackagesProcessor())
   .processor(new AddPackageExportsProcessor())
+  .processor(new AddSubpackageExportsProcessor())
   .processor(new MarkdownCodeProcessor())
   .processor(COLLECT_LINKABLE_SYMBOLS_PROCESSOR_NAME, (log, createDocMessage) => new CollectLinkableSymbolsProcessor(log, createDocMessage))
   .factory('API_DOC_TYPES_TO_RENDER', (EXPORT_DOC_TYPES) => EXPORT_DOC_TYPES.concat(['component', 'directive', 'pipe']))
-  //Configure our package
   .config((readFilesProcessor, readTypeScriptModules, tsParser) => {
 
     // Tell TypeScript how to load modules that start with `@daffodil`

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

@@ -10,7 +10,7 @@ import { getPackageInfo } from '../helpers/generateApiList';
  */
 export class AddPackageExportsProcessor implements Processor {
   readonly name = 'addPackageExports';
-  readonly $runAfter = ['docs-processed'];
+  readonly $runAfter = ['docs-processed', 'addSubpackageExports'];
   readonly $runBefore = ['rendering-docs'];
 
   docTypes = ['package'];

tools/dgeni/src/transforms/daffodil-api-package/processors/add-subpackage-exports.ts

@@ -0,0 +1,27 @@
+import { Document } from 'dgeni';
+
+import { FilterableProcessor } from '../../../utils/filterable-processor.type';
+import { isSubpackage } from '../../../utils/package-path';
+
+/**
+ * Adds subpackage entry point docs to the containing package doc.
+ */
+export class AddSubpackageExportsProcessor implements FilterableProcessor {
+  readonly name = 'addSubpackageExports';
+  readonly $runAfter = ['docs-processed'];
+  readonly $runBefore = ['rendering-docs'];
+
+  docTypes = ['package'];
+
+  $process(docs: Array<Document>): Array<Document> {
+    return docs.map((doc) => {
+      if (this.docTypes.includes(doc.docType)) {
+        const subPackages = docs.filter((d) =>
+          d.docType === 'package' && isSubpackage(doc, d),
+        );
+        doc.exports.push(...subPackages);
+      }
+      return doc;
+    });
+  }
+}

tools/dgeni/src/utils/package-path.ts

@@ -0,0 +1,10 @@
+import { Document } from 'dgeni';
+
+/**
+ * Returns `true` if `possibleSub` is a direct subpackage of `root`.
+ */
+export const isSubpackage = (root: Document, possibleSub: Document): boolean => {
+  const rootSegs = root.id.split('/');
+  const subSegs = possibleSub.id.split('/');
+  return rootSegs.join() === subSegs.slice(0, subSegs.length - 1).join();
+};