Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions libs/docs-utils/src/path.ts
Original file line number Diff line number Diff line change
@@ -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';
1 change: 1 addition & 0 deletions libs/docs-utils/src/public_api.ts
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
export { crossOsFilename } from './cross-os-filename';
export * from './kind/public_api';
export * from './path';
9 changes: 8 additions & 1 deletion tools/dgeni/src/processors/generateApiList.ts
Original file line number Diff line number Diff line change
@@ -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'];
1 change: 0 additions & 1 deletion tools/dgeni/src/transforms/config.ts
Original file line number Diff line number Diff line change
@@ -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');
5 changes: 3 additions & 2 deletions tools/dgeni/src/transforms/daffodil-api-package/index.ts
Original file line number Diff line number Diff line change
@@ -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',
});
})
6 changes: 2 additions & 4 deletions tools/dgeni/src/transforms/daffodil-base-package/index.ts
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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',
65 changes: 22 additions & 43 deletions tools/dgeni/src/transforms/daffodil-guides-package/index.ts
Original file line number Diff line number Diff line change
@@ -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)]);
Original file line number Diff line number Diff line change
@@ -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)),
});