feat(dgeni): add doc kind to document (#3037)

tools/dgeni/src/processors/add-kind.ts

@@ -0,0 +1,35 @@
+import { Document } from 'dgeni';
+
+import {
+  DaffDocKind,
+  daffDocsGetKind,
+} from '@daffodil/docs-utils';
+
+import { FilterableProcessor } from '../utils/filterable-processor.type';
+
+/**
+ * A dgeni document which has had the doc kind added.
+ */
+export interface KindedDocument extends Document {
+  kind: DaffDocKind;
+}
+
+/**
+ * Adds doc kind based on file path.
+ */
+export class AddKindProcessor implements FilterableProcessor {
+  readonly name = 'addKind';
+  readonly $runAfter = ['files-read'];
+  readonly $runBefore = ['processing-docs'];
+
+  docTypes = [];
+
+  $process(docs: Array<Document>): Array<KindedDocument> {
+    return docs.map((doc) => {
+      if (this.docTypes.includes(doc.docType)) {
+        doc.kind = daffDocsGetKind(doc.fileInfo.filePath);
+      }
+      return doc;
+    });
+  }
+}

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

@@ -10,6 +10,7 @@ import { transformApiNavList } from './helpers/generateApiList';
 import { AddPackageExportsProcessor } from './processors/add-package-exports';
 import { RemoveDuplicatesProcessor } from './processors/remove-duplicates';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
+import { AddKindProcessor } from '../../processors/add-kind';
 import { AddInheritedDocsContentProcessor } from '../../processors/addInheritedDocsContent';
 import { AddLinkTagToDaffodilReferencesProcessor } from '../../processors/addLinkTagToDaffodilReferences';
 import { CleanSelectorsProcessor } from '../../processors/cleanSelectors';
@@ -69,8 +70,9 @@ export const apiDocsBase = new Package('api-base', [
     readTypeScriptModules.basePath = API_SOURCE_PATH;
     readTypeScriptModules.hidePrivateMembers = true;
   })
-  .config((markdown: MarkdownCodeProcessor, EXPORT_DOC_TYPES) => {
+  .config((markdown: MarkdownCodeProcessor, EXPORT_DOC_TYPES, addKind: AddKindProcessor) => {
     markdown.docTypes.push(...EXPORT_DOC_TYPES);
+    addKind.docTypes.push(...EXPORT_DOC_TYPES);
     markdown.contentKey = 'description';
   })
   .config((computePathsProcessor, EXPORT_DOC_TYPES) => {

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

@@ -10,6 +10,7 @@ import * as basePackage from 'dgeni-packages/base';
 import * as nunjucksPackage from 'dgeni-packages/nunjucks';
 import * as path from 'path';
 
+import { AddKindProcessor } from '../../processors/add-kind';
 import { ConvertToJsonProcessor } from '../../processors/convertToJson';
 import {
   PROJECT_ROOT,
@@ -21,6 +22,7 @@ export const daffodilBasePackage = new Package('daffodil-base', [
   basePackage,
   nunjucksPackage,
 ])
+  .processor(new AddKindProcessor())
   .processor('convertToJson', (log, createDocMessage) => new ConvertToJsonProcessor(log, createDocMessage))
   .factory('packageInfo', () => require(path.resolve(PROJECT_ROOT, 'package.json')))
 

tools/dgeni/src/transforms/daffodil-design-examples-package/index.ts

@@ -13,6 +13,7 @@ import { DesignExampleDocumentCreatorProcessor } from './processors/designExampl
 import { DesignExampleFilterProcessor } from './processors/exampleFileCollator';
 import { DesignExampleHighlightCodeProcessor } from './processors/highlightCode';
 import { designExampleReaderFactory } from './reader/example.reader';
+import { AddKindProcessor } from '../../processors/add-kind';
 import { CleanSelectorsProcessor } from '../../processors/cleanSelectors';
 import { FilterContainedDocsProcessor } from '../../processors/filterDocs';
 import {
@@ -21,6 +22,8 @@ import {
 } from '../config';
 import { daffodilBasePackage } from '../daffodil-base-package';
 
+const docTypes = ['design-example'];
+
 export const designExamplePackage = new Package('daffodil-design-examples', [daffodilBasePackage])
   .factory('designExampleReader', designExampleReaderFactory)
   .processor('convertToJson', (log, createDocMessage) =>  new DesignExampleConvertToJsonProcessor(log, createDocMessage))
@@ -37,12 +40,13 @@ export const designExamplePackage = new Package('daffodil-design-examples', [daf
       { include: ['**/examples/src/*/*.*']},
     ];
   })
-  .config((convertToJson) => {
-    convertToJson.docTypes = convertToJson.docTypes.concat(['design-example']);
+  .config((convertToJson, addKind: AddKindProcessor) => {
+    convertToJson.docTypes.push(...docTypes);
+    addKind.docTypes.push(...docTypes);
   })
   .config((computePathsProcessor) => {
     computePathsProcessor.pathTemplates.push({
-      docTypes: ['design-example'],
+      docTypes,
       getPath: (doc) => {
         doc.moduleFolder = `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[DaffDocKind.EXAMPLE]}/${doc.id}`;
         return doc.moduleFolder;
@@ -56,7 +60,7 @@ export const designExamplePackage = new Package('daffodil-design-examples', [daf
   })
   .config((computeIdsProcessor) => {
     computeIdsProcessor.idTemplates.push({
-      docTypes: ['design-example'],
+      docTypes,
       getId: (doc) => doc.id,
       getAliases: (doc) =>[doc.id],
     });

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

@@ -9,6 +9,7 @@ import {
 import { transformGuideDoc } from './helpers/generateGuideList';
 import { guideFileReaderFactory } from './reader/guide-file.reader';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
+import { AddKindProcessor } from '../../processors/add-kind';
 import { GenerateNavListProcessor } from '../../processors/generateNavList';
 import { MarkdownCodeProcessor } from '../../processors/markdown';
 import { outputPathsConfigurator } from '../../utils/configurator/output';
@@ -22,24 +23,27 @@ import {
 } from '../config';
 import { daffodilBasePackage } from '../daffodil-base-package';
 
+const docTypes = ['guide'];
+
 const base = new Package('daffodil-guides-base', [daffodilBasePackage])
   .factory('guideFileReader', guideFileReaderFactory)
   .processor(new MarkdownCodeProcessor())
-  .config((markdown: MarkdownCodeProcessor) => markdown.docTypes = ['guide'])
+  .config((markdown: MarkdownCodeProcessor, addKind: AddKindProcessor, convertToJson) => {
+    addKind.docTypes.push(...docTypes);
+    markdown.docTypes.push(...docTypes);
+    convertToJson.docTypes = convertToJson.docTypes.concat(docTypes);
+  })
   .config((readFilesProcessor, guideFileReader) => {
     readFilesProcessor.$enabled = true;
     readFilesProcessor.fileReaders.push(guideFileReader);
   })
-  .config((convertToJson) => {
-    convertToJson.docTypes = convertToJson.docTypes.concat(['guide']);
-  })
   .config((templateFinder) => {
     // Where to find the templates for the API doc rendering
     templateFinder.templateFolders.unshift(GUIDES_TEMPLATES_PATH);
   })
   .config((computeIdsProcessor) => {
     computeIdsProcessor.idTemplates.push({
-      docTypes: ['guide'],
+      docTypes,
       getId: (doc) => doc
         .fileInfo
         .relativePath
@@ -59,7 +63,7 @@ const base = new Package('daffodil-guides-base', [daffodilBasePackage])
 export const packageDocsPackage = outputPathsConfigurator({
   kind: DaffDocKind.PACKAGE,
   outputPath: DAFF_DOCS_PATH,
-  docTypes: ['guide'],
+  docTypes,
 })(new Package('daffodil-package-docs', [base]))
   .config((readFilesProcessor) => {
     readFilesProcessor.basePath = API_SOURCE_PATH;
@@ -72,22 +76,22 @@ export const guideDocsPackage = pathsConfigurator({
   kind: DaffDocKind.GUIDE,
   outputPath: DAFF_DOCS_PATH,
   inputPathBase: DOCS_SOURCE_PATH,
-  docTypes: ['guide'],
+  docTypes,
 })(new Package('daffodil-guide', [base]));
 
 export const explanationDocsPackage = pathsConfigurator({
   kind: DaffDocKind.EXPLANATION,
   outputPath: DAFF_DOCS_PATH,
   inputPathBase: DOCS_SOURCE_PATH,
-  docTypes: ['guide'],
+  docTypes,
 })(new Package('daffodil-explanation', [base]));
 //
 
 // design
 export const designDocsPackage = outputPathsConfigurator({
   kind: DaffDocKind.PACKAGE,
   outputPath: `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`,
-  docTypes: ['guide'],
+  docTypes,
 })(new Package('design-packages', [base]))
   .config((readFilesProcessor) => {
     readFilesProcessor.basePath = DESIGN_PATH;
@@ -100,13 +104,13 @@ export const designGuidesPackage = pathsConfigurator({
   kind: DaffDocKind.GUIDE,
   outputPath: `${DAFF_DOCS_PATH}/${DAFF_DOCS_DESIGN_PATH}`,
   inputPathBase: DESIGN_PATH,
-  docTypes: ['guide'],
+  docTypes,
 })(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'],
+  docTypes,
 })(new Package('design-explanations', [base]));
 //

tools/dgeni/src/utils/filterable-processor.type.ts

@@ -0,0 +1,12 @@
+import { Processor } from 'dgeni';
+
+/**
+ * A type of processor that will only process docs of a specfic type.
+ * All other doc types will be ignored and pass through unchanged.
+ */
+export interface FilterableProcessor extends Processor {
+  /**
+   * The types of docs to process.
+   */
+  docTypes: Array<string>;
+}