diff --git a/libs/docs-utils/src/path.ts b/libs/docs-utils/src/path.ts new file mode 100644 index 0000000000..a69e827505 --- /dev/null +++ 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 index e5c6605a60..d512e5f592 100644 --- 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 index 33445e6f83..f9a809ecad 100644 --- 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 index 577321f1fb..c57191577b 100644 --- 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 index 00aed855bc..f5d5cc0ed9 100644 --- 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 index 0cfc929eef..869c94c7de 100644 --- 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 index ac8777e730..601f9586b7 100644 --- 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 index 4a8442d410..c102987b14 100644 --- 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 index 6abad2ad00..d72ff4e01e 100644 --- a/tools/dgeni/src/transforms/daffodil-guides-package/processors/generateGuideList.ts +++ b/tools/dgeni/src/transforms/daffodil-guides-package/processors/generateGuideList.ts @@ -5,14 +5,10 @@ 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, }); @@ -20,8 +16,7 @@ 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)), });