feat(dgeni,docs-utils): centralize docs path segment (#2962)

graycoreio · Aug 9, 2024 · 5554fd0 · 5554fd0
1 parent 5ffbb6f
commit 5554fd0
Show file tree

Hide file tree

Showing 9 changed files with 47 additions and 61 deletions.
diff --git a/libs/docs-utils/src/path.ts b/libs/docs-utils/src/path.ts
@@ -0,0 +1,4 @@
+/**
+ * The path segment (both for filesystem and routing) under which the docs will be stored.
+ */
+export const DAFF_DOCS_PATH = 'docs';
diff --git a/libs/docs-utils/src/public_api.ts b/libs/docs-utils/src/public_api.ts
@@ -1,2 +1,3 @@
 export { crossOsFilename } from './cross-os-filename';
 export * from './kind/public_api';
+export * from './path';
diff --git a/tools/dgeni/src/processors/generateApiList.ts b/tools/dgeni/src/processors/generateApiList.ts
@@ -3,14 +3,21 @@ import {
   Document,
 } from 'dgeni';
 
+import {
+  DAFF_DOC_KIND_PATH_SEGMENT_MAP,
+  DAFF_DOCS_PATH,
+  DaffDocKind,
+} from '@daffodil/docs-utils';
+
 export interface GenerateApiListConfiguration {
   outputFolder: string;
 }
 
 export const DefaultGenerateApiListConfiguration: GenerateApiListConfiguration = {
-  outputFolder: 'api',
+  outputFolder: `${DAFF_DOCS_PATH}/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[DaffDocKind.API]}`,
 };
 
+// TODO: combine with generate guide list processor
 export class GenerateApiListProcessor implements Processor {
   name = 'generateApiList';
   $runAfter = ['docs-processed'];

diff --git a/tools/dgeni/src/transforms/config.ts b/tools/dgeni/src/transforms/config.ts
@@ -11,7 +11,6 @@ export const API_TEMPLATES_PATH = resolve(TEMPLATES_PATH, 'api');
 export const SRC_PATH = resolve(DAFFIO_PATH, 'src');
 export const DIST_PATH = resolve(PROJECT_ROOT, 'dist');
 export const OUTPUT_PATH = resolve(DIST_PATH, '');
-export const DOCS_OUTPUT_PATH = resolve(OUTPUT_PATH, 'docs');
 export const API_SOURCE_PATH = resolve(PROJECT_ROOT, 'libs');
 export const DOCS_SOURCE_PATH = resolve(PROJECT_ROOT, 'docs');
 export const GUIDES_TEMPLATES_PATH = resolve(TEMPLATES_PATH, 'guides');

diff --git a/tools/dgeni/src/transforms/daffodil-api-package/index.ts b/tools/dgeni/src/transforms/daffodil-api-package/index.ts
@@ -2,6 +2,7 @@ import { Package } from 'dgeni';
 
 import {
   DAFF_DOC_KIND_PATH_SEGMENT_MAP,
+  DAFF_DOCS_PATH,
   DaffDocKind,
 } from '@daffodil/docs-utils';
 
@@ -74,14 +75,14 @@ export const apiDocs = new Package('daffodil-api', [
     computePathsProcessor.pathTemplates.push({
       docTypes: ['package'],
       getPath: (doc) => {
-        doc.moduleFolder = `${API_SEGMENT}/${doc.id.replace(/\/src$/, '')}`;
+        doc.moduleFolder = `${DAFF_DOCS_PATH}/${API_SEGMENT}/${doc.id.replace(/\/src$/, '')}`;
         return doc.moduleFolder;
       },
       outputPathTemplate: '${moduleFolder}.json',
     });
     computePathsProcessor.pathTemplates.push({
       docTypes: EXPORT_DOC_TYPES,
-      pathTemplate: 'docs/${moduleDoc.moduleFolder}/${name}',
+      pathTemplate: '${moduleDoc.moduleFolder}/${name}',
       outputPathTemplate: '${moduleDoc.moduleFolder}/${safeName}.json',
     });
   })

diff --git a/tools/dgeni/src/transforms/daffodil-base-package/index.ts b/tools/dgeni/src/transforms/daffodil-base-package/index.ts
@@ -13,8 +13,8 @@ import * as path from 'path';
 import { ConvertToJsonProcessor } from '../../processors/convertToJson';
 import {
   PROJECT_ROOT,
-  DOCS_OUTPUT_PATH,
   TEMPLATES_PATH,
+  OUTPUT_PATH,
 } from '../config';
 
 export const daffodilBasePackage = new Package('daffodil-base', [
@@ -33,9 +33,7 @@ export const daffodilBasePackage = new Package('daffodil-base', [
 
 // Where do we write the output files?
   .config((writeFilesProcessor) => {
-    // TODO: consider changing this to the parent so that the doc paths automatically include `docs/`
-    // we would avoid having to do things like https://github.com/graycoreio/daffodil/blob/db026e91c2e46b6ac895da86003f2f612800d917/tools/dgeni/src/transforms/daffodil-guides-package/processors/generateGuideList.ts#L15
-    writeFilesProcessor.outputFolder = DOCS_OUTPUT_PATH;
+    writeFilesProcessor.outputFolder = OUTPUT_PATH;
   })
 
 // Configure nunjucks rendering of docs via templates

diff --git a/tools/dgeni/src/transforms/daffodil-design-examples-package/index.ts b/tools/dgeni/src/transforms/daffodil-design-examples-package/index.ts
@@ -1,6 +1,8 @@
 import { Package } from 'dgeni';
 
 
+import { DAFF_DOCS_PATH } from '@daffodil/docs-utils';
+
 import { DesignExampleConvertToJsonProcessor } from './processors/convertToJson';
 import { DesignExampleDocumentCreatorProcessor } from './processors/designExampleDocumentCreator';
 import { DesignExampleFilterProcessor } from './processors/exampleFileCollator';
@@ -40,7 +42,7 @@ export const designExamplePackage = new Package('daffodil-design-examples', [daf
     computePathsProcessor.pathTemplates.push({
       docTypes: ['design-example'],
       getPath: (doc) => {
-        doc.moduleFolder = `${DOCS_SEGMENT}/${doc.id}`;
+        doc.moduleFolder = `${DAFF_DOCS_PATH}/${DOCS_SEGMENT}/${doc.id}`;
         return doc.moduleFolder;
       },
       outputPathTemplate: '${moduleFolder}.json',

diff --git a/tools/dgeni/src/transforms/daffodil-guides-package/index.ts b/tools/dgeni/src/transforms/daffodil-guides-package/index.ts
@@ -1,5 +1,11 @@
 import { Package } from 'dgeni';
 
+import {
+  DAFF_DOC_KIND_PATH_SEGMENT_MAP,
+  DAFF_DOCS_PATH,
+  DaffDocKind,
+} from '@daffodil/docs-utils';
+
 import { GenerateGuideListProcessor } from './processors/generateGuideList';
 import { guideFileReaderFactory } from './reader/guide-file.reader';
 import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-packages';
@@ -23,7 +29,7 @@ const base = new Package('daffodil-guides-base', [daffodilBasePackage])
     convertToJson.docTypes = convertToJson.docTypes.concat(['guide']);
   })
   .config((templateFinder) => {
-  // Where to find the templates for the API doc rendering
+    // Where to find the templates for the API doc rendering
     templateFinder.templateFolders.unshift(GUIDES_TEMPLATES_PATH);
   })
   .config((computeIdsProcessor) => {
@@ -41,66 +47,39 @@ const base = new Package('daffodil-guides-base', [daffodilBasePackage])
     });
   });
 
-export const packageDocsPackage = new Package('daffodil-package-docs', [base])
-  .processor(new GenerateGuideListProcessor({ outputFolder: 'packages' }))
-  .config((readFilesProcessor) => {
-    readFilesProcessor.basePath = API_SOURCE_PATH;
-    readFilesProcessor.sourceFiles = [
-      { include: [DAFF_DGENI_EXCLUDED_PACKAGES_REGEX + '*/**/README.md', DAFF_DGENI_EXCLUDED_PACKAGES_REGEX + '/guides/**/*.md']},
-    ];
+const baseFactory = (kind: DaffDocKind) => new Package(`daffodil-${kind}-base`, [base])
+  .processor(new GenerateGuideListProcessor())
+  .config((generateGuideList: GenerateGuideListProcessor) => {
+    generateGuideList.outputFolder = `${DAFF_DOCS_PATH}/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[kind]}`;
   })
   .config((computePathsProcessor) => {
-    const DOCS_SEGMENT = 'packages';
     computePathsProcessor.pathTemplates.push({
       docTypes: ['guide'],
-      getPath: (doc)  =>{
-        doc.moduleFolder = `${DOCS_SEGMENT}/${doc.id.replace(/\/docs/, '')}`;
-        return doc.moduleFolder;
+      getPath: (doc) => {
+        doc.moduleFolder = `${DAFF_DOCS_PATH}/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[kind]}/${doc.id}`;
+        return `/${doc.moduleFolder}`;
       },
       outputPathTemplate: '${moduleFolder}.json',
     });
   });
 
-export const guideDocsPackage = new Package('daffodil-guide-docs', [base])
-  .processor(new GenerateGuideListProcessor({ outputFolder: 'guides' }))
+const globalDocFactory = (kind: DaffDocKind) => new Package(`daffodil-global-${kind}`, [baseFactory(kind)])
   .config((readFilesProcessor) => {
-    readFilesProcessor.basePath = `${DOCS_SOURCE_PATH}/guides`;
+    readFilesProcessor.basePath = `${DOCS_SOURCE_PATH}/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[kind]}`;
     readFilesProcessor.sourceFiles = [
       { include: [
         '**/*.md',
       ]},
     ];
-  })
-  .config((computePathsProcessor) => {
-    const DOCS_SEGMENT = 'guides';
-    computePathsProcessor.pathTemplates.push({
-      docTypes: ['guide'],
-      getPath: (doc)  =>{
-        doc.moduleFolder = `${DOCS_SEGMENT}/${doc.id.replace(/\/docs/, '')}`;
-        return doc.moduleFolder;
-      },
-      outputPathTemplate: '${moduleFolder}.json',
-    });
   });
 
-export const explanationDocsPackage = new Package('daffodil-explanation-docs', [base])
-  .processor(new GenerateGuideListProcessor({ outputFolder: 'explanations' }))
+export const packageDocsPackage = new Package('daffodil-package-docs', [baseFactory(DaffDocKind.PACKAGE)])
   .config((readFilesProcessor) => {
-    readFilesProcessor.basePath = `${DOCS_SOURCE_PATH}/explanations`;
+    readFilesProcessor.basePath = API_SOURCE_PATH;
     readFilesProcessor.sourceFiles = [
-      { include: [
-        '**/*.md',
-      ]},
+      { include: [DAFF_DGENI_EXCLUDED_PACKAGES_REGEX + '*/**/README.md', DAFF_DGENI_EXCLUDED_PACKAGES_REGEX + '/guides/**/*.md']},
     ];
-  })
-  .config((computePathsProcessor) => {
-    const DOCS_SEGMENT = 'explanations';
-    computePathsProcessor.pathTemplates.push({
-      docTypes: ['guide'],
-      getPath: (doc)  =>{
-        doc.moduleFolder = `${DOCS_SEGMENT}/${doc.id.replace(/\/docs/, '')}`;
-        return doc.moduleFolder;
-      },
-      outputPathTemplate: '${moduleFolder}.json',
-    });
   });
+
+export const guideDocsPackage = new Package('daffodil-guide-docs', [globalDocFactory(DaffDocKind.GUIDE)]);
+export const explanationDocsPackage = new Package('daffodil-explanation-docs', [globalDocFactory(DaffDocKind.EXPLANATION)]);
diff --git a/tools/dgeni/src/transforms/daffodil-guides-package/processors/generateGuideList.ts b/tools/dgeni/src/transforms/daffodil-guides-package/processors/generateGuideList.ts
@@ -5,23 +5,18 @@ import {
 
 import { generateNavigationTrieFromDocuments } from '../helpers/navigation-trie';
 
-export interface GenerateGuideListConfiguration {
-  outputFolder: string;
-};
-
 export const transformGuideDoc = (doc: Document): TransformedDocument => ({
   id: doc.id,
   title: doc.title,
-  path: `docs/${doc.path}`,
+  path: doc.path,
   tableOfContents: doc.tableOfContents,
 });
 
 export class GenerateGuideListProcessor implements Processor {
   name = 'generateGuideList';
   $runAfter = ['docs-processed'];
   $runBefore = ['rendering-docs'];
-
-  constructor(private config: GenerateGuideListConfiguration) {}
+  outputFolder: string;
 
   $process(docs: Document[]): Document[] {
     // hardcode design path
@@ -34,8 +29,8 @@ export class GenerateGuideListProcessor implements Processor {
     docs.push({
       docType: 'navigation-list',
       template: 'guide-list.template.json',
-      path: this.config.outputFolder + '/index.json',
-      outputPath: this.config.outputFolder + '/index.json',
+      path: this.outputFolder + '/index.json',
+      outputPath: this.outputFolder + '/index.json',
       data: generateNavigationTrieFromDocuments(docsWithoutDesignChildren.map(transformGuideDoc)),
     });